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| About Net Yaroze 


In order to get started with Net Yaroze, you should have C programming experience at some level of 
competence and you should be familiar with 2D graphic creation/editing tools. You should also have a 
basic understanding of 3D modelling packages and sound creation/editing tools. Together these will 


help you get the most out of your Net Yaroze System. 


The Net Yaroze Manual Set 


There are three books in the Net Yaroze manual set. 


1. Start-Up Guide 
An introductory booklet explaining the contents and requirements of the Net Yaroze Starter Kit. 
The Start-Up Guide gives step-by-step instructions on setting up the Net Yaroze software on 


your PC. It also explains how to run software on the Net Yaroze system. 


2.  User’s Guide 


A reference manual explaining how to create software for the Net Yaroze system. 


3. Library Reference (this document) 


A manual listing and describing the functions and structures in the Net Yaroze libraries. 
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CVECTOR 
8-bit 3D (color) vector 

Structure 

typedef struct { 

unsigned char r, g, b, cd; 

} CVECTOR; 
Members 

r,g,b Vector elements 

cd System reserved 
Explanation 





CVECTOR is used to define the structure of an 8-bit 3D (color) vector. 
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DISPENV 
Structure 
typedef struct { 
} DISPENV; 
Members 
disp 
screen 
isinter 
isrgb24 


Display environment 


RECT disp; 

RECT screen; 
unsigned char isinter; 
unsigned char isrgb24; 


unsigned char pad0, pad1; 


Frame buffer display area. 
disp defines the display area within the frame buffer. 
The width of disp can be set to 256, 320, 360, 512 or 640. 
The height of disp can be set to 240 or 480. 
Output screen display area. 
screen is calculated on the basis of a standard monitor screen and is 
independent of the value of disp. The standard monitor screen uses 
(0,0) for the coordinate of the upper left-hand corner and (256, 240) 
for the coordinate of the lower right-hand corner. 
Interlaced mode flag 
0: Non-interlaced mode 
1: Interlaced mode 


24-bit mode flag 
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0: 16-bit mode 
1: 24 bit mode 


pad0, padl System reserved 


Explanation 


DISPENV is used to specify parameters for the display environment such as screen 


display mode and frame buffer display position. 
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DRAWENV 
Structure 
typedef struct { 
} DRAWENV; 
Members 
clip 
ofs 
tw 


Drawing environment 


RECT clip; 

short ofs[2]; 

RECT tw; 

unsigned short tpage; 
unsigned char dtd; 
unsigned char dfe; 
unsigned char ishg; 


unsigned char 70, g0, 60; 
DR_ENV dr _env; 


Drawing area. 

clip specifies the rectangular area used for drawing. Drawing will 
not be performed outside the area specified by clip. 

Offset. 

The values (ofs[0], ofs[1]) are used as offsets when calculating the 
address that is used for drawing in the frame buffer. The offsets are 
added to the values of all coordinates to determine the address used 
by drawing commands when drawing in the frame buffer. 


Texture window. 
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tw specifies the rectangular area within the texture page that is 


used repeatedly for applying textures. 


tpage Texture page initial value. 
dtd Dither treatment flag 
0: Dithering OFF. 
1: Dithering ON. 
Dfe Display area drawing flag 

0: Drawing to the display area is 

disabled. 

1: Drawing to the display area is enabled. 

isbg Clear drawing area flag 

0: The drawing area is not cleared when 
the drawing environment is 
established. 

1: The entire clipped area is painted with 
the brightness values (r0,g0,b0) when 
the drawing environment is 
established. 

r0,g0,b0 Background color. Valid only when isbg = 1. 
dr_env System reserved. 


Explanation 


DRAWENYV sets basic parameters related to drawing such as the drawing offset and the 


drawing clip area. 


Notes 





Drawing can be performed in the region (0, 0)-(1023, 511) within the drawing space. 
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Offsets and addresses to which the offset has been added are wrapped around at (-1024, 
-1024)-(1023, 1023). 


Values that can be specified for the texture window are limited to the combinations 


shown in the following table. 


tw.x | 0 | muttipte of 16] multiple of 32 multiple of 128 
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GsBG 
BG (background picture) handler 
Structure 
struct GsBG { 
unsigned long attribute; 
short x,y; 
short w, h; 
short scrollx, scrolly; 
unsigned char r, g, b; 
GsMAP *map; 
short mx, my; 
short scalex, scaley; 
long rotate; 
E 
Members 
attribute 32-bit attribute (see the description in GsSPRITE) 
x,y Display position of the upper left-hand point 
w,h BG display size (in pixels) 
scrollx, scrolly x,y scroll values 
r,g,b Display brightness is set in r, g, b. (Normal brightness is 
128.) 
map Pointer to map data 
mx, my Rotation and enlargement central point coordinates 
scalex, scaley Scale values in x and y directions 


14 


EEE Graphics Library Structures 





Explanation 


rotate Rotation angle (4096 = 1 degree) 


GsBG is a structure used to describe a background. A background (BG) consists of a 
large rectangle drawn from GsMAP data based upon a combination of small rectangles 
defined by GsCELL data. Every background has an associated GsBG structure. The 
background may be manipulated via this structure. 

To enter a GsBG object in an ordering table, use GsSortBg(). 

x, y specify the screen display position. 

w, h specify the BG display size in pixels, and are not dependent on cell size or map 
size. 

If the display area is larger than the map, the content of the map is repeatedly displayed. 
(this is referred to as tiling) 

scrollx, scrolly specify the offset from the map display position in dots. 

r, g, b specify the brightness values for red, green, and blue. The allowed range is 0 to 
255. 128 is the brightness of the original pattern; 255 represents a two-fold increase in 
brightness. 

map is a pointer to the start of the map data. Map data is represented by the GSMAP 
structure. 

mx, my specify the center of rotation and scaling as relative coordinates. The upper left- 
hand point of the BG is the point of origin. For example, if rotation is around the center 
of the BG, these values should be specified as w/2 and h/2, respectively. 

scalex, scaley specify enlargement/reduction values in the x and y directions. These 
values represent units of 4096 (which is equivalent to a fixed point value of 1.0). 
scalex and scaley can be set up to 8 times the original size. 


rotate specifies the amount of rotation around the Z-axis. 
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GsBOXF 
Rectangle handler 
Structure 
struct GSBOXF { 
unsigned long attribute; 
short x,y; 
unsigned short w, h; 
unsigned char r, g, b; 
E 
Members 
attribute Attribute bits as shown below. (Bits not defined below are 
reserved by the system) 
28-29: Semi-transparency rate 
0: 0.5 x Back + 0.5 x Forward 
1: 1.0 x Back + 1.0 x Forward 
2: 1.0 x Back - 1.0 x Forward 
3: 1.0 x Back + 0.25 x Forward 
30: Semi-transparency mode 
0: Semi-transparency OFF 
1: Semi-transparency ON 
31: Display mode 
0: Enable display 
1: Display display 
x,y Display position (upper left-hand point) 
w,h Size of rectangle (width, height) 
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r,g,b Drawing color 


Explanation 


GsBOXF is a structure used to represent a rectangle drawn in a single color. The 


GsSortBoxFill() function can be used to enter a GSBOXF object in the ordering table. 


17 


EEE Graphics Library Structures 











GsCELL 
Cells which define a BG 
Structure 
struct GsCELL { 
unsigned char u,v; 
unsigned short cba; 
unsigned short flag; 
unsigned short tpage; 
bs 
Members 
u Offset (X-direction) within the page 
v Offset (Y-direction) within the page 
cba CLUT ID 
flag Inversion control flag 
tpage Texture page number 
Explanation 





A rectangular array of GsCell structures is used to describe individual cells that fit 
together to create a background (BG). Each individual GsCell structure defines a 
rectangular portion of the overall BG. 

cba displays the position within the frame buffer of a CLUT corresponding to the cell, 


and has the following meaning. 
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X position of CLUT/16 





Bit 6~15 Y position of CLUT 


tpage is a page number that indicates the position of a sprite pattern within the frame 
buffer. 

The u and v parameters specify the offset position for the sprite pattern within the 
texture page defined by tpage. 

flag controls whether the image is flipped during drawing. The meaning of each bit is 


as shown below. 


a 
Vertical flip (0 = no flip, 1 = flip) 


Horizontal flip (0 = no flip, 1 = flip) 
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GsCOORDINATE2 


Matrix-type coordinate system 


Structure 





struct GCCOORDINATE2 { 
unsigned long flg; 
MATRIX coord; 
MATRIX workm; 
GsCOORD2PARM *param; 
GsCOORDINATE2 *super; 





E 
Members 
flg Flag indicating whether coord was rewritten 
coord The matrix 
workm Result of multiplying this coordinate system with the WORLD 
coordinate system 
param Pointer for scaling, rotation and translation parameters 
super Pointer to the parent coordinate system 
Explanation 





GsCOORDINATE2 is defined by the matrix coord and a pointer to the parent 
coordinate system. 

workm retains the result of matrix multiplication in each node of GCOOORDINATE2 
from WORLD coordinates and performed by the GsGetLw() and GsGetLs() functions. 
However, workm does not store the result of matrix multiplication for a coordinate 


system that is directly coupled to the WORLD coordinate system. 
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fig is used during GsGetLw() and GsGetLs() to omit calculations for a node when 
calculations were already performed. When //g is set to 1, calculations are omitted. 
When flg is set to 0, calculations are performed. The programmer must clear this flag 


whenever coord is changed otherwise the GsGetLw() and GsGetLs() functions will 


not execute properly. 
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GsDOBJ2 


Structure 





Members 





Explanation 
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Object structure definition used by the GSCOORDINATE2 3D 
object handler 


struct GSDOBJ2 { 
unsigned long attribute; 
GsCOORDINATE2 *coord2; 
unsigned long *tmd; 


unsigned long id; 


} 

attribute Object attribute (32-bits) 

coord2 Pointer to a local coordinate system 
tmd Pointer to model data 

id System reserved 


GsDOBJ2 structures can be used to manipulate 3D models. Each object in a 3D model 
has an associated GSDOBJ2 structure. 

The GsDOBJ2 structure can be linked to TMD file model data using 
GsLinkObject4(). The GsDOBJ2 structure can be registered in the ordering table using 
GsSortObject4(). 

The coord2 parameter is a pointer to a GSCOORDINATE2 structure defining the 
object's coordinate system. The location, inclination, and size of the object are defined 


in a matrix in this structure. 
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tmd contains the starting address of TMD model data stored in memory. tmd is 
calculated and set using GsLinkObject4(). 
attribute is 32 bits and is used to store various display attributes as shown below. All 
other bits not defined below are reserved by the system. 
(a) Bit 3: Light source calculation mode 
This bit controls whether light source calculation will be performed using FOG. 
0: Normal mode without FOG. This is the fastest mode requiring the least 
amount of calculation time. 
1: FOG mode. FOG attributes are set in the GFRFOGPARAM structure 
and updated using the GsSetFogParam() function. 
(b) Bit 5: Light source calculation mode control bit 
This bit controls whether light source calculation mode is determined by bit 3 of the 
attribute field or by the lighting mode set by GsSetLightMode(). 
0: Lighting mode is set by GsSetLightMode(). Bit 3 of the attribute field is 
ignored. 
1: Lighting mode is set according to bit 3 of the attribute field. 
(b) Bit 6: Light source calculation ON/OFF switch 
This bit is used to switch light source calculation on and off. 
When light source calculation is turned off, a texture-mapped polygon is displayed in 
the original texture color. An unmapped polygon is displayed in the model data color. 
(c) Bit 30: Semi-transparency ON/OFF 
This bit is used to switch semi-transparency on and off. 
This bit must be used with the uppermost bit (STP bit) of the texture color field to 
enable semi-transparency. (The texture color field is the texture pattern when direct 
mode is set and the CLUT color field when indexed mode is set). The semi-transparency 
and non-transparency of each pixel may also be controlled using the STP bit. 


(d) Bit 31: Display ON/OFF 
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This bit is used to switch the display on and off. 


(e) Bits 9-11: Automatic partitioning (polygon subdivision) 


0: 
l: 


4: 
5: 


No automatic partitioning 
2x2 partitioning 

4x4 partitioning 

8x8 partitioning 

16x16 partitioning 


32x32 partitioning 


These bits specify the number of subdivisions for the automatic partitioning 


function. Automatic partitioning, or polygon subdivision, causes all the polygons 


contained within an object to subdivide. It is used for reducing texture distortion 


and preventing fragmentation of adjacent polygons. Note that division should be 


kept to a minimum in order to prevent the number of polygons from increasing 


exponentially. 
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GsFOGPARAM 


Fog (depth cue) information 


Structure 





struct GFFOGPARAM { 
short dqa; 
long dqb; 
unsigned char rfc, gfc, bfc; 





E 

Members 
dqa Parameter specifying the degree of blending with respect to 
depth 
dqb Parameter specifying the degree of blending with respect to 
depth 
rfc, gfe, bfe Background colors 

Explanation 





GsFOGPARAM describes fog (depth cue) information 
dqa and dqb are background color attenuation coefficients. They can be calculated 
using the following formulas: 

dqa = -df * 4096/64/h 

dqb = 1.25 * 4096 * 4096 
df is the distance where the attenuation coefficient is 1; that is, the distance from the 
viewpoint to the point where the background colors are completely blended. 
h is the distance from the viewpoint to the screen and is also known as the projection 


distance. 
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GsF_LIGHT 
Parallel light source 
Structure 
struct GsF_LIGHT { 
long vx, vy, vz; 
unsigned char r, g, b; 
bs 
Members 
VX, VY, VZ Light source directional vectors 
r,g,b Light colors 
Explanation 





GsF_LIGHT describes parallel light source information. It is set by the 
GsSetFlatLight() function. 

Up to three parallel light sources can be set simultaneously. 

The light source directional vector is specified by vx, vy, vz. It is unnecessary for the 
programmer to perform normalization as this is done by the GsSetFlatLight() function. 
A polygon whose normal vectors are opposite to these directional vectors is exposed 
to the strongest light. 


Light source colors are specified in the 8-bit values r, g, b. 
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GsGLINE 
Straight line handler with gradation 
Structure 
struct GsGLINE { 
unsigned long attribute; 
short x0, y0; 
short x/, vl; 
unsigned char 70,20, 60; 
unsigned char r/1,g/,b1; 
E 
Members 
attribute Attribute bits as shown below. (Bits not defined below are 
reserved by the system) 
28-29: Semi-transparency rate 
0: 0.5 x Back + 0.5 x Forward 
1: 1.0 x Back + 1.0 x Forward 
2: 1.0 x Back - 1.0 x Forward 
3: 1.0 x Back + 0.25 x Forward 
30: Semi-transparency mode 
0: Semi-transparency OFF 
1: Semi-transparency ON 
31: Display mode 
0: Enable display 
1: Disable display 
x0, y0 Drawing starting point position 
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Explanation 
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xl,yl Drawing ending point position 
r0, g0, b0 Drawing color of the starting point 
rl,gl,bl Drawing color of the ending point 


GsGLINE is a structure used to represent straight lines with gradation. It is the same 
as GsLINE except that drawing colors for the starting point and ending point may be 


specified separately. 
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GsIMAGE 


Structure 





struct GSIMAGE { 


Members 





pmode 


PX, Py 
pw, ph 
pixel 
cx, cy 


cw, ch 


Image data structure information 


short pmode; 

short px, py; 

unsigned short pw, ph; 
unsigned long *pixel; 
short cx, cy; 

unsigned short cw, ch; 


unsigned long *clut; 


Pixel mode 
0: 4-bit CLUT 
1: 8-bit CLUT 
2: 16-bit Direct 
3: 24-bit Direct 
4: Multiple mode combinations 


Pixel data storage location within the frame buffer 
Pixel data width and height 

Pointer to pixel data 

CLUT data storage location within the frame buffer 


CLUT data width and height 
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Explanation 


30 


clut Pointer to CLUT data 


GsIMAGE is loaded with TIM format data information using the GsGetTimInfo() 
function. 
For information on the TIM file format, please refer to the Net Yaroze Members' Web 


site. 
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GsLINE 
Straight line handler 
Structure 
struct GsLINE { 
unsigned long attribute; 
short x0, v0; 
short x/,v/; 
unsigned char r, g, b; 
j 
Members 
attribute Attribute bits as shown below. (Bits not defined below are 
reserved by the system) 
28-29: Semi-transparency rate 
0: 0.5 x Back + 0.5 x Forward 
1: 1.0 x Back + 1.0 x Forward 
2: 1.0 x Back - 1.0 x Forward 
3: 1.0 x Back + 0.25 x Forward 
30: Semi-transparency mode 
0: Semi-transparency OFF 
1: Semi-transparency ON 
31: Display mode 
0: Enable display 
1: Disable display 
x0, y0 Drawing starting point position 
xl,yl Drawing ending point position 
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Explanation 


32 


r,g,b Drawing color 


GsLINE is a structure that represents straight lines. Use GsSortLine() to register a 
GsLINE in the ordering table. 
attribute is 32 bits, and sets various attributes for display as shown below. 
(a) Semi-transparency rate (bit 28-29) 
If semi-transparency is turned on using bit 30, bits 28 and 29 are used to set the pixel 
blending method. Normal semi-transparency processing is performed when these bits 
are set to 0, pixel addition when set to 1, pixel subtraction when set to 2, and 25% 
addition when set to 3. 
(b) Semi-transparency mode (bit 30) 

Turns semi-transparency ON/OFF 
(c) Display mode (bit 31) 

Turns the display ON/OFF 
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GsMAP 

Structure 
struct GIMAP { 
} 

Members 





cellw, cellh 
ncellw, ncellh 
base 


index 


Explanation 


BG composition MAP 


unsigned char cellw, cellh; 
unsigned short ncellw, ncellh; 
GsCELL *base; 


unsigned short *index; 


Cell size (0 is the same as 256) 
Size of the background (BG) in cells 
Pointer to the GsCELL structure array 


Pointer to cell information 


The GsMAP structure contains map data that is used to create a background from 


GsCELL data. Map data is managed by cell index array information. 


cellw, cellh specify the size of one cell in pixels. Note that one BG is made up of cells of 


the same size. 


ncellw and ncellh specify the size of the BG map in units of cells. 


base specifies the starting address of the GsCELL array. 
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index specifies the starting address of the cell data table. Cell data is a list of index 
values whose size is equivalent to (ncellw * ncellh) for the array specified by base. Ifa 


cell value is OxFFFF it indicates a NULL (transparent) cell. 
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GsOT 
Ordering table header 
Structure 
struct GsOT { 
unsigned short length; 
GsOT_TAG *org; 
unsigned short offset; 
unsigned short point; 
GsOT_TAG *tag; 
E 
Members 
length Bit length of the ordering table (OT) 
org Pointer to start address of GSOT_TAG table 
offset OT screen coordinate system Z-axis offset 
point OT screen coordinate system Z-axis typical value 
tag Pointer to current GOOT_TAG 
Explanation 





The GsOT structure describes the header of the ordering table. This header has pointers 
to the actual ordering table array, specified by the org and tag members. These members 
are initialized using the GsClearOT() function. 

The org member always points to the start of the ordering table. The tag field points to 


the element within the ordering table at which drawing will take place. 
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Notes 





See also 
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The /ength field indicates the size of the ordering table. It is a value from 1-14 where 
the actual ordering table size is 2**length (i.e. a value of 14 indicates an array of 
16384 GsOT_TAG items, while a value of 8 indicates an array of 256 GSOT_TAG 
items). 

org points to a GSOT_TAG array running from 0-1. If the value "14" is specified, org 
points to a GSOT_TAG array running from 0-16384. 

The GsClearOt() function initializes memory from org up through the size indicated by 
length. Note that memory will be destroyed if the size of the GSOT_TAG array pointed 
to by org is greater than that specified by length. 

point is used by the GsSortOt() function in the sorting of ordering tables. 

The ordering table Z-axis offset is specified by offset. For example, if offset = 256, the 


start of the ordering table is Z = 256. (Not yet supported.) 


The length and org values should be set first. The other members are set by the 


GsClearOt() function. 


GsClearOt(), GsDrawOt(), GsSortOt()* 
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GsOT_TAG 


Ordering table element 


Structure 





struct GSOT_TAG { 
unsigned p : 24; 


unsigned char num : 8; 





bs 
Members 

p Pointer to next item in ordering table list 

num Number of words in current GPU packet (i.e. primitive) 
Explanation 





An ordering table is a linked list of GSOT_TAG structures and various types of GPU 
primitive structures. 

The p field of a GsOT_TAG structures indicates the least significant 24-bits of a 
pointer to the next item in the list. A value of OxFFFFFF indicates the end of the list. 
The GsOT structure is used to manage an array of GSOT_TAG structures. Memory 
should be allocated for the GSOT_TAG structures after the GsOT structure is 


initialized. 
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GsRVIEW2 
Viewpoint position (REFERENCE-type) 
Structure 
struct GSRVIEW2 { 
long vpx, vpy, vpz; 
long vpx, vpy, vpz; 
long 7z; 
GsCOORDINATE2 *super 
j 
Members 
vpx, vpy, Vpz Viewpoint coordinates 
VIX, Vry, VIZ Reference point coordinates 
rz Viewpoint twist 
super Pointer to the coordinate system that sets the viewpoint 
(GsCOORDINATE2 type) 
Explanation 





GsVIEW2 holds information about the viewpoint. It is set by the GsSetRefView2() 
function. 

vpx, vpy, vpz specify the viewpoint coordinates in the coordinate system specified by 
super. 

wrx, vry, vrz specify the reference coordinates in the coordinate system specified by 


super. 
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When the Z-axis is a vector from the viewpoint to the reference point, rz specifies the 
viewpoint twist, or screen inclination against the Z-axis. It is represented as an 
integer, with 4096 equivalent to one degree. 

The viewpoint and reference point coordinate systems are set in super. 

As an example of using this function, an airplane cockpit view can be realized simply 


by setting super to the airplane coordinate system. 
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GsSPRITE 
Sprite handler 
Structure 
struct GSSPRITE { 
unsigned long attribute; 
short x,y; 
unsigned short w, h; 
unsigned short tpage; 
unsigned char u,v; 
short cx, cy; 
unsigned char r, g, b; 
short mx,my; 
short scalex, scaley; 
long rotate; 
bs 
Members 
attribute 32-bit attribute field (explanation is given below) 
x,y Display position of the upper left-hand point 
w,h Width and height of the sprite (Not displayed if w or h is 0.) 
tpage Sprite pattern texture page number 
u,v Sprite pattern offset within the page 
CX, CY Sprite CLUT addressr, 
g,b Display brightness for r, g, and b (normal brightness is 128) 
mx, my Rotation and enlargement central point coordinates 
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scalex, scaley 
rotate 


attribute bits 


Explanation 


Scale values in x and y directions 
Rotation angle (4096 = 1 degree) 
(Bits not defined below are reserved by the system) 
6: Brightness adjustment switch 
0: ON 
1: OFF 


24-25: Sprite pattern color mode 


0: 4-bit CLUT 
1: 8-bit CLUT 
2: 15-bit Direct 


27: Rotation & scaling functions 
0: ON 
1s OFF 


28-29: Semi-transparency rate 





0: 0.5 x Back + 0.5 x Forward 
1: 1.0 x Back + 1.0 x Forward 
2: 1.0 x Back - 1.0 x Forward 
3: 1.0 x Back + 0.25 x Forward 


30: Semi-transparency mode 
0: Semi-transparency OFF 
1: Semi-transparency ON 
31: Sprite display mode 


0: Displayed 
1: Not displayed 


GsSPRITE is a structure used to display a sprite. This structure makes it possible to 


manipulate each sprite via its parameters. 
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To enter a GsSPRITE in an ordering table, use GsSortSprite() or GsSortFastSprite(). 
x,y specify the screen display position. mx, my specify the point in the sprite pattern 
used as the display position in GsSortSprite(); in GsSortFastSprite(), the point at the 
upper left-hand corner of the sprite is used as the display position. 
w, h specify the width and height of the sprite in pixels. 
tpage specifies the texture page number (0-31) of the sprite pattern. 
u, v specify the offset within the page from the upper left-hand point of the sprite 
pattern. The range that may be specified is (0, 0) - (255, 255). 
cx, cy specify the starting position of the CLUT (color palette) as a VRAM address. 
(Valid for 4-bit/8-bit mode only.) 
r,g,b specify the brightness values for red, green, and blue. The allowed range is 0 to 
255. 128 is the brightness of the original pattern; 255 represents a two-fold increase in 
brightness. 
mx, my specify the coordinates for the center of rotation and scaling. The upper left- 
hand point of the sprite is the point of origin. For example, if rotation is around the 
center of the sprite, mx and my should be specified as w/2 and h/2, respectively. 
scalex, scaley specify enlargement/reduction values in the x and y directions. These 
values represent units of 4096 (which is equivalent to a fixed point value of 1.0). 
scalex and scaley can be set up to 8 times the original size. 
rotate specifies the amount of rotation around the Z-axis and is represented as an 
integer, where 4096 is equivalent to 1 degree. 
attribute is 32 bits, and sets various attributes for display. An explanation of each bit 
follows. Bits not defined below are reserved by the system. 
(a) Brightness adjustment switch (bit 6) 
This bit sets whether or not the sprite pattern pixel colors are to be drawn with 
brightness adjusted according to the (r,g,b) values. When this bit is 1, brightness 


is not adjusted and the (r,g,b) values are ignored. 
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(b) Sprite pattern color mode (bit 24-25) 


A sprite pattern can use either 4-bit color mode or 8-bit color mode, both of which 
use the color table, and 15-bit mode, which directly displays colors. These bits are 


used to set one of these color modes. Please see above for bit definitions. 


(c) Rotation & scaling functions (bit 27) 


This bit turns on or off the sprite scaling function. If rotation or scaling of the sprite 
is not needed, this bit should be set to OFF for high speed processing. 


GsSortFastSprite() ignores this bit and always set the scaling function to OFF. 


(d) Semi-transparency rate (bit 28-29) 


These bits set the method of pixel blending together with bit 30, when semi- 
transparency is turned on. Normal semi-transparent processing is performed when 
these bits are set to 0, pixel addition when set to 1, pixel subtraction when set to 2, 


and 25% addition when set to 3. 


(e) Semi-transparency mode (bit 30) 


®© 


This bit turns semi-transparency on or off. It must be used with the uppermost bit 
(STP bit) of the texture color field to turn semi-transparency on (texture pattern 
when in direct mode and CLUT color field when in indexed mode). The semi- 
transparency and non-transparency of each pixel may also be controlled using this 
STP bit. 

Sprite display mode (bit 31) 


This bit turns the display mode on and off. 
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GsVIEW2 
Viewpoint position (Matrix-type) 
Structure 
struct GSVIEW2 { 
MATRIX view; 
GsCOORDINATE2 *super 
E 
Members 
view Matrix for conversion from parent coordinates to viewpoint 
coordinates 
super Pointer to the coordinate system that sets the viewpoint 
Explanation 





GsVIEW2 sets the viewpoint coordinate system. It directly specifies the matrix for 
converting from the parent coordinate system to the viewpoint coordinate system in 


view. 


The function that sets GsVIEW2 is GsSetView2(). 
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MATRIX 
3 x 3 matrix 
Structure 
typedef struct { 
short m[3][3]; 
long ¢[3]; 
} MATRIX; 
Members 
m Element values of the 3 x 3 matrix 
t Amount of translation 
Explanation 





MATRIX defines a 3 x 3 matrix. The value of each element is specified by m/i//j/. 


t[i] specifies the amount of translation after conversion. 
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RECT 
Frame buffer rectangular area 
Structure 
typedef struct { 
short x, y; 
short w, h; 
} RECT; 
Members 
x,y Coordinates for the upper left-hand corner of the rectangular 
area 
w,h Width and height of the rectangular area 
Explanation 





RECT is used to specify a rectangular area in the frame buffer. Negative values or values 


that exceed the size of the frame buffer (1024 x 512) cannot be used. 
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SVECTOR 
16-bit 3D vector 
Structure 
typedef struct { 
short vx, vy; 
short vz, pad; 
} SVECTOR; 
Members 
VX, VY, VZ Vector elements 
pad System reserved 
Explanation 





SVECTOR is used to define the structure of a 16-bit 3D vector. 
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VECTOR 
32-bit 3D vector 
Structure 
typedef struct { 
long vx, vy; 
long vz, pad; 
} VECTOR; 
Members 
VX, VY, VZ Vector elements 
pad System reserved 
Explanation 





VECTOR is used to define the structure of a 32-bit 3D vector. 
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ApplyMatrix 


Multiplies a vector by a matrix 


Syntax 





VECTOR* ApplyMatrix ( 
MATRIX *m, 

SVECTOR *v0, 

VECTOR *v/ 


) 
Arguments 


m Pointer to input matrix 
vO Pointer to input short vector 


vl Pointer to result vector 


Explanation 





The short vector v0 is multiplied by the matrix m beginning with the rightmost end. 
The product is stored in vector v/. 
The argument format is as follows: 

m->m{[i]{j] : (1,3,12) 

v0->vx,vy,vz :(1,15,0) 


vl->vx,vy,vz :(1,31,0) 


Return Value 





The vector product v/is returned. 


Notes 





This function destroys the rotation matrix. 
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ApplyMatrixLV 


Multiplies a vector by a matrix 


Syntax 





VECTOR* ApplyMatrixLV ( 
MATRIX *m, 

VECTOR *v0, 

VECTOR *v/ 

) 


Arguments 
m Pointer to input matrix 
v0 Pointer to input vector 


vl Pointer to result vector 


Explanation 
The vector v0 is multiplied by the matrix m beginning with the rightmost end. The 
product is stored in vector v/. 
The argument format is as follows: 
m->m{[i]fj] : (1,3,12) 
v0->vx,vy,vz :(1,31,0) 


vl->vx,vy,vz :(1,31,0) 


Return Value 





The vector product v/is returned. 
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Notes 





This function destroys the rotation matrix. 
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ApplyMatrixSV 


Multiplies a vector by a matrix 


Syntax 





SVECTOR* ApplyMatrixSV ( 
MATRIX *m, 

SVECTOR *v0, 

SVECTOR *v/ 


) 


Arguments 
m Pointer to input matrix 
vO Pointer to input short vector 


vl Pointer to result short vector 


Explanation 
The short vector v0 is multiplied by the matrix m beginning with the rightmost end. 
The product is stored in short vector v1. 
The argument format is as follows: 
m->m[i]fj] : (1,3,12) 
v0->vx,vy,vz :(1,15,0) 


vl->vx,vy,vz :(1,15,0) 


Return Value 





The vector product v/is returned. 
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Notes 





This function destroys the rotation matrix. 
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ClearImage 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 
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Fills the frame buffer with a specified pixel value 


int ClearImage ( 
RECT *recp, 
u_char r, 

u_char g, 

u_char b 


) 


recp Pointer to the rectangular area to be cleared in the frame buffer 


r,g,b Pixel value to be used for clearing 


The rectangular area of the frame buffer specified by recp is cleared with the pixel value 


specified by (7,g,5). 


The slot number of the GPU’s draw/command queue where the command resides is 


returned. 


Movelmage() is a non-blocking function, therefore DrawSync() must be used to 
determine the completion of transfer. 

The transfer is not affected by clipping or offsetting that may be in effect for the drawing 
environment. 
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Comp Matrix 


Performs composite coordinate transformation 


Syntax 





MATRIX*CompMatrix ( 
MATRIX*m0, 
MATRIX*m/, 


MATRIX*m2 
) 


Arguments 


m0 Pointer to input matrix 
ml Pointer to input matrix 


m2 Pointer to result matrix 


Explanation 





The composite coordinate transformation of matrix m0 and matrix m1 (including 
translation) is performed. The result is placed in matrix m2. 
The following algorithm is used. 
[m2->m] = [m0->m] * [m1 ->m] 
(m2->t) = [m0->m] * (m1->t) + (m0->t) 
However the values of the m1->t elements must be within the range of [-2" ; 2”) : 
The argument format is as follows:: 
m0->m[i]fj] : (1,3,12) 
m0->t[i]: (1,31,0) 
ml->m[i][jj] : (1,3,12) 


m1->t[i]: (1,15,0) 
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Return Value 





Notes 
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m2->m{il[j] : (1,3,12) 
m2->t[i]: (1,31,0) 


The result matrix m2 is returned. 


This function destroys the rotation matrix. 
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DrawSync 


Syntax 





Arguments 


Explanation 





Return Value 





Waits for completion of all drawing 


int DrawSync ( 


int mode 


) 


mode 0: Waits for completion of all non-blocking functions 
registered in the GPU’s command/execution queue. 
1: The current slot number of the GPU’s command/execution 


queue is returned. 


DrawSyne waits until all drawing has completed. 


The current slot number of the GPU’s command/execution queue is returned. 
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FntFlush 
Draws the contents of a print stream 

Syntax 

u_long *FntFlush( 

int id 

) 
Arguments 

id Print Stream ID 
Explanation 





The contents of the specified print stream are drawn in the frame buffer. FntFlush() 
initializes and draws a sprite primitive list corresponding to the characters in the 


specified print stream. 


Return Value 





A pointer to the start of the OT used for drawing is returned. 


Notes 





After drawing is completed, the contents of the print stream are flushed. 
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FntLoad 


Syntax 





Arguments 





Explanation 





Return Value 





Notes 





Loads the system font patterns into the frame buffer 


void FntLoad( 


int tx, 

int ty 

) 

tx, ty Upper left-hand coordinate where the font patterns will be 
loaded into the frame buffer 


The system font patterns used for debugging are loaded into the frame buffer beginning 
at the coordinates specified by (tx, ty). All print streams are initialized. The system font 


patterns are 4-bit textures and require an area of size 256 x 128. 


None 


FntLoad() must always be executed before FntOpen() and FntFlush(). 


The font area must not overlap with the frame buffer area used by the application. 
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FntOpen 
Opens a print stream 
Syntax 
int FntOpen( 
int x, 
int y, 
int w, 
int A, 
int isbg, 
int n 
) 
Arguments 
x,y Display start position 
w, h Display area 
isbg Background auto-clear flag 
0: Clear the background to (0,0,0) when displaying. 
1: Do not clear the background. 
n Maximum number of characters that can be drawn 
Explanation 





The stream used for on-screen printing is opened. Subsequently, character strings up to 
n characters long can be drawn in the rectangular area of the frame buffer specified by 
(x,y)-(x+w, y+h) using the FntPrint() function. 


Ifisbg has a value of “1”, the background is cleared when a character string is drawn. 
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Return 
Value 





The ID of the print stream that was opened is returned. 


Notes 





Up to 8 streams can be opened simultaneously. 


Opened streams cannot be closed until the next FntLoad(). 
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FntPrint 
Sends output to a print stream 

Syntax 

int FntPrint( 

int id, 

char *format, 

) 
Arguments 

id Print stream ID 

format Print format string 
Explanation 





The character string specified as an argument is formatted and sent as output to the 
specified print stream. Formatting is performed according to format and is identical to 


the specification of the format string for the C library fprintf() function. 


Return Value 





The number of characters in the stream is returned. 


Notes 





The character string is not displayed until FntFlush() is executed. 
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GetClut 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





u_short GetClut ( 
int x, 
int y 


) 


xy 


Calculates value of member clut in a primitive 


Frame buffer address of the CLUT 


The texture CLUT ID is calculated and its value is returned. 


The calculated CLUT ID is returned. 


The CLUT address is limited to a multiple of 16 in the x direction. 
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GetTPage 
Calculates value of member tpage in a primitive 
Syntax 
u_short GetTPage ( 
int tp, 
int abr, 
int x, 
int y 
) 
Arguments 
tp Texture mode 
0: 4-bit CLUT 
1: 8-bit CLUT 
2: 16-bit Direct 
abr Semi-transparency rate 
0: 0.5 x Back + 0.5 x Forward 
1: 1.0 x Back + 1.0 x Forward 
2: 1.0 x Back - 1.0 x Forward 
3: 1.0 x Back + 0.25 x Forward 
xy Texture page address 
Explanation 





The texture page ID of the texture page address specified by (x, y) is calculated and its 


value is returned. 
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Return Value 





The calculated texture page ID is returned. 


Notes 





The semi-transparency rate is also valid for polygons for which texture mapping is not 


performed. 


The texture page address is limited to a multiple of 64 in the x direction and a multiple 


of 256 in the y direction. 
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GsClearOt 
Initializes an OT 

Syntax 

void GsClearOt ( 

unsigned short offset, 

unsigned short point, 

GsOT *otp 

) 
Arguments 

offset Ordering table offset value 

point Ordering table typical Z value 

otp Pointer to an ordering table 
Explanation 





The ordering table pointed to by ofp is initialized. 

offset specifies the Z value used for the start of the ordering table. point specifies a 
typical Z value for the entire ordering table. point is used to set depth priority when 
multiple ordering tables are linked together. 

The length field of the GsOT structure must be properly set before this function is 


called so that the size of the ordering table to be cleared can be determined. 


Return Value 





None 


See Also 





GsOT, GsDrawOt() 
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GsDefDispBuff 


Syntax 





Arguments 


Explanation 





Defines the double buffers used for drawing 


void GsDefDispBuff ( 
int x0, 

int y0, 

int x/, 

int yl, 

) 


x0, yO Buffer 0 origin (upper left-hand) coordinates 


xl, yl Buffer 1 origin (upper left-hand) coordinates 


The display areas in the frame buffer used for double buffering are established. 

The x0, y0 parameters specify the coordinates within the frame buffer for buffer #0. The 
xl, yl parameters specify the coordinates within the frame buffer for buffer #1. If x0, y0 
and x1, yl are specified as the same coordinates in non-interlaced mode, the double 
buffers are released. However, double-buffer swapping of even-numbered and odd- 
numbered fields is performed automatically when x0, y0 and x1, y1 are specified as the 
same coordinates in interlaced mode. 

Normally, buffer #0 is located at (0,0) and buffer #1 is located at (0, yres), where yres is 


the vertical resolution specified using the GsInitGraph() function. 
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Return Value 





See Also 
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The GsSwapDispBuffer() function is used to swap the double buffers. Double buffering 
is implemented using the GPU/GTE offset which can be set using GsInitGraph(). 
When using the GPU to manage the offset, the double buffer offset will be added at the 


time of drawing, not at the time of packet creation. 


None 


GsInitGraph(), GsSwapDispBuff() 
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GsDrawOt 


Syntax 





Arguments 


Explanation 





Notes 





Return Value 





Execute drawing commands associated with an OT 


void GsDrawOt ( 


GsOT *otp 
) 


otp Pointer to an ordering table 


The drawing commands that are entered in the ordering table pointed to by otp are 
executed. Drawing is performed by the GPU. 
GsDrawOt() is a non-blocking function and returns immediately. The actual drawing 


is performed in the background. 


This function does not execute correctly if it is called when GPU drawing is in 
progress. ResetGraph(1) should be used to terminate any current drawing process or 
DrawSync(0) should be used to wait until drawing is completed before this function is 


called. 


None 
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See Also 





GsOT, GsClearOt() 
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GsGetActiveBuff 


Gets the drawing buffer index 


Syntax 





int GsGetActiveBuff ( void ) 


Arguments 


None 


Explanation 





The double buffer index (PSDIDX) is obtained and its value is returned. 

The value of the index is either 0 or 1. 

By entering the index in the external variables PSDBASEX[] and PSDBASEY{], the 
two-dimensional address of the double buffer origin (upper left-hand coordinate) in the 


frame buffer can be obtained. 


Return Value 





The double buffer index (0 for buffer 0; 1 for buffer 1) is returned. 


See Also 





PSDIDX 
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GsGetLs 


Syntax 





Arguments 


Explanation 
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Calculates a local-to-screen transformation matrix 


void GsGetLs ( 
GsCOORDINATE2 *coord, 


MATRIX *m 

) 

coord Pointer to a local coordinate system 
m Pointer to result matrix 


The local-to-screen transformation matrix of the coordinate system pointed to by coord 
is calculated and the result is stored in the matrix pointed to by m. 

The GSCOORDINATE2 structure pointed to by coord describes a node in the 
hierarchical coordinate system. When the transformation matrix is calculated, 
calculation is performed for each node in the hierarchy and results are stored in the 
workm member within each node of the coordinate system. To improve performance, 
calculation is only performed for nodes which have changed, as determined by the 
value of the flag member, even when GsGetLw() is called repeatedly. It should be 
noted that when a parent node is changed, all subordinate nodes will be recalculated 
automatically even if their flag members are set. 

It is the responsibility of the programmer to clear flag within each node if the member 
coord has changed, otherwise the transformation matrix will not be calculated 


correctly. 
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Return Value 





None 


See Also 





GsSetLsMatrix() 
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GsGetLw 


Syntax 





Arguments 


Explanation 





74 


Calculates a local-to-world transformation matrix 


void GsGetLw ( 
GsCOORDINATE2 *coord, 


MATRIX *m 

) 

coord Pointer to a local coordinate system 
m Pointer to the result matrix 


The local-to-world transformation matrix of the coordinate system pointed to by coord 
is calculated and the result is stored in the matrix pointed to by m. 

The GSCOORDINATE2 structure pointed to by coord describes a node in the 
hierarchical coordinate system. When the transformation matrix is calculated, 
calculation is performed for each node in the hierarchy and results are stored in the 
workm member within each node of the coordinate system. To improve performance, 
calculation is only performed for nodes which have changed, as determined by the 
value of the flag member, even when GsGetLw() is called repeatedly. However, when a 
parent node is changed, all subordinate nodes will be recalculated automatically even 
if their flag members are set. 

It is the responsibility of the programmer to clear flag within each node if the member 
coord has changed, otherwise the transformation matrix will not be calculated 


correctly. 
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Return Value 





None 


See Also 





GsGetLws(), GsSetLightMatrix() 
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GsGetLws 


Syntax 





Arguments 


Explanation 





Return Value 
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Calculates both local-to-world and local-to-screen 
transformation matrices 


void GsGetLws ( 


GsCOORDINATE2 *coord2 


MATRIX */w, 

MATRIX */s 

) 

coord2 Pointer to local coordinate system 

lw Pointer to local-to-world coordinate system result matrix 
ls Pointer to local-to-screen coordinate system result matrix 


The local-to-world and the local-to-screen transformation matrices for the coordinate 
system pointed to by coord? are calculated and the results are stored in the matrices 
pointed to by /w and ls, respectively. 

The local-to-world matrix must be specified when light source calculation is performed. 
GsGetLws() is a fast method for obtaining this matrix. 

GsGetLws() is equivalent to calling GsGetLw() followed by GsGetLs(), only with 


faster performance. 


None 
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See Also 





GsGetLs(), GsGetWs() 
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GsGetTimInfo 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Gets TIM data header 


void GsGetTimInfo ( 
unsigned long *tim, 


GsIMAGE *im 


) 
tim Pointer to TIM data header 
im Pointer to result image structure 


Information obtained from the TIM data header pointed to by tim is placed in the 
GsIMAGE structure pointed to by im. 

TIM data begins at the address after the ID, which is 4 bytes after the start of the TIM 
file. 

For a description of the TIM file format, please refer to the Net Yaroze Members' Web 


site. 


None 


GsIMAGE 
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GsGetWorkBase 


Gets the base address of the drawing command area 


Syntax 





PACKET *GsGetWorkBase ( void ) 


Arguments 


None 


Explanation 





The address of the first packet in the drawing command work area is obtained and its 
value is returned. 


Note that the type PACKET is defined as an unsigned char in libps.h. 


Return Value 





The address of the first packet in the drawing command work area is returned. 


See Also 





GsSetWorkBase(), GsOUT_PACKET_P 
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GsIncFrame 


Increments the frame ID 


Syntax 





GsIncFrame() 


Arguments 


None 


Explanation 





The global variable PSDCNT is incremented by 1. 

PSDCNT is used by GsGetLw(), GsGetLs() and GsGetLws() to determine the validity 
of the matrix cache when the double buffer is swapped. PSDCNT is 32 bits in length, 
and restarts at 1 rather than 0 when it overflows. 

GsIncFrame() is automatically called from within GsSwapDispBuff(). If the double 
buffer is swapped without using GsSwapDispBuff(), but the functions GsGetLw(), 
GsGetLs() and GsGetLws() are used, GsIncFrame() needs to be called every time the 


double buffer is swapped. 


See Also 





PSDCNT, GsGetLw(), GsGetLs(), GsGetLws(), GsSwapDispBuff() 
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Table: Graphics External Variables 


2-dimensional clipping area 


PSDOFSX [2] unsigned short Double buffer base point (X coordinate) 
Set by GsDefDispbuffQ) 





PSDOFSY [2] unsigned short Double buffer base point (Y coordinate) 
Set by GsDefDispbuff() 


GsLSMATRIX MATRIX Local screen matrix 
GsWSMATRIX MATRIX World screen matrix 
ee en | Set by GsSetRefView(), etc. 


GsLIGHT_MODE Default light mode 


GsLIGHTWSMATRIX MATRIX Light matrix 
Set by GsSetFlatLight() 


GsOUT_PACKET P unsigned long Pointer to top of packet area 


GsTON unsigned long Attribute decoding result (semi-transparency) 
GsDISPON unsigned long Attribute decoding result (display / no display 
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GsInit3D 
Initializes the 3D graphics system 
Syntax 
void GsInit3D ( void ) 
Arguments 
None 
Explanation 





The 3D graphics system within the library is initialized. 
The 3D graphics system needs to be initialized by this function first, so that 3D 
processing functions such as GsSetRefView(), GsInitCoordinate2() and 
GsSortObject4() can be used. 
The following are the steps in the initialization process. 

(1) The screen origin is reset to the center of the screen. 


(2) The default light source is set to LIGHT NORMAL. 


Return Value 








None 

Notes 
It is necessary to initialize the graphics system with GsInitGraph() before calling this 
function. 

See Also 





GsInitGraph(), GsSetRefView(), GsInitCoordinate2(), GsSortObject4() 
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GsInitCoordinate2 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Initialize a local coordinate system 


void GsInitCoordinate2 ( 
GsCOORDINATE2 *super, 
GsCOORDINATE2 *base 


) 
super Pointer to the parent coordinate system 
base Pointer to the local coordinate system to be initialized 


The local coordinate system pointed to by base and its parent coordinate system 
pointed to by super are initialized. 
The base coordinate system is initialized using base- >coord whereas the parent 


coordinate system is initialized using super; i.e. the base- >super member is ignored 


None 
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GsInitFixBg16 


Syntax 





Arguments 


Explanation 
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Initializes high-speed BG work area 


void GsInitFixBg16 ( 
GsBG *bg, 


unsigned long *work 


) 
bg Pointer to a background descriptor 
work Pointer to the work area (primitive area) 


The work area used by the GsSortFixBg16() function is initialized. 
The size of the work area varies with the screen resolution according to the following 


formula: 


Work area size (in long units) = 
(((ScreenW/CellW+1)*(ScreenH/CellH+1+1)*6+4)*2+2) 
where 
ScreenH = screen height in pixels (240/480) 
ScreenW = screen width in pixels (256/320/384/5 12/640) 
CellH = cell height (in pixels) 
CellW = cell width (in pixels) 
GsInitFixBg16() should only be executed once. It does not need to be executed every 


frame. 
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Return Value 





None 


See Also 





GsSortFixBg16() 
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GsInitGraph 


Syntax 





Arguments 


86 


Initializes the graphics system 


void GsInitGraph ( 


int x_res, 
int y_res, 
int intl, 
int dither, 
int vram 
) 
x_res Horizontal resolution (256/320/384/5 12/640) 
y_res Vertical resolution (240/480) 
intl Interlace display flag (bit 0) 
0: Non-interlaced 
1: Interlaced 
Double Buffer Offset Mode (bit 2) 
0: GTE offset 
1: GPU offset 
dither Dither processing flag 
0: OFF 
1: ON 
vram Frame buffer mode 
0: 16-bit 


Explanation 


Return Value 
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1: 24-bit 


The graphics system is initialized. 

The operational settings of the graphics system are reflected in the global variables 
GsDISPENV and GSDRAWENV. The program can use these global variables to 
determine the current settings of the graphics system. 

The Double Buffer Offset Mode controls the offset that is added to the frame buffer when 
drawing is performed. The Mode determines whether the offset is managed by GTE or 
the GPU. 

When the Mode is specified as GTE, the offset is added to the drawing address when 
the drawing packet is created. When the Mode is specified as GPU, the offset is added 
when drawing is performed. Having the GPU manage the offset is usually preferred 
because the offset is not included in the drawing packet. 

In 24-bit mode, the frame buffer can only operate in image display mode and polygons 
cannot be drawn. 

GsInitGraph() must be called to initialize the graphics system. GsInitGraph() also 
initializes the internal structures GIDMATRIX and GsIDMATRIX2. These structures 


must be initialized before any of the Gs*** functions can be used. 


None 
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GsLinkObject4 


Links an object to TMD data 


Syntax 





void GsLinkObject4 ( 
unsigned long *tmd, 
GsDOBJ2 *obj_base, 


unsigned long n 


) 
Arguments 
tmd Pointer to TMD data 
obj_base Pointer to the linking object structure 
n Index of the object to be linked 
Explanation 





The object pointed to by obj_base is linked to the n-th object in the TMD data 


pointed to by tmd. This allows TMD 3D objects to be handled using GSDOBJ2. 


Return Value 








None 

Notes 
Objects linked by GsLinkObject4() can be registered in the ordering table by 
GsSortObject4(). 

See Also 





GsSortObject4(), GsDOBJ2 
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GsMapModelingData 


Syntax 





Arguments 


Explanation 





Return Value 





Maps TMD data to real addresses 


void GsMapModelingData ( 
unsigned long *p 


) 


Pp Pointer to starting address of TMD data 


Offsets within the TMD data pointed to by p are converted into real addresses. The 
converted addresses are stored back in the TMD data. 

TMD data includes various fields which contain the memory addresses of certain pieces 
of data. During the preparation of TMD data, however, the memory address where the 
data will be loaded is not yet known. Therefore, address fields in the TMD data are 
stored as offsets from the start of the data. The GsMapModelingData() function changes 
these offsets into real addresses after the TMD data has been loaded into memory. This 
must be done before the TMD data can be used. 

TMD data begins at the address after the ID which is 4 bytes after the start of the TMD 
file. 

For a description of the TMD file format, please refer to the Net Yaroze Members' Web 


site. 


None 
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Notes 





A flag is set in the TMD data to indicate that the offset addresses have been converted 


into real addresses. So, no side effects occur even if GSMapModelingData() is called 


repeatedly. 
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GsScaleScreen 


Syntax 





Arguments 


Explanation 





Scales the screen coordinate system 


void GsScaleScreen ( 


SVECTOR *scale 
) 


scale Pointer to the scale vector (each element is a 12-bit integer) 


The screen coordinate system is scaled relative to the world coordinate system by an 
amount specified in the vector pointed to by scale. 

Each element of scale is a 12-bit integer. Scaling is performed relative to the original 
screen coordinate system set by GsSetView2() and GsSetRefView2(). If each element of 
scale is set to the value ONE, the screen coordinate system is reset to its original 
values. Note that ONE is defined to be the value 4096. 

World coordinates are represented in 32 bits, whereas screen coordinates are 
represented in 16 bits. The different representations would normally cause problems 
such as Far Clip proximity. GsScaleScreen() eliminates these problems by scaling the 
screen coordinate system within the wider area of the world coordinate system. 

For example, if the elements of scale are each set to ONE/2, the screen coordinate 
system will be expanded to the equivalent of 17 bits after scaling. Since the precision 


of screen coordinate values is only 16 bits, the low-order bit will be ignored. 


91 


EEE Graphics Library Functions 





Return Value 
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Note that when scaling is performed, objects that exist in screen coordinate systems 
having different scaling factors cannot be entered in the same ordering table. For 
example, in order to enter an object that was calculated with the normal scale screen 
coordinate system in an ordering table which already contains an object with a 1/2 
scale screen coordinate system, it is necessary to right-shift the excess bit before 
entering the object in the ordering table. This can be done by specifying the shift 


amount when calling GsSortObject4(). 


None 
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GsSetAmbient 


Set ambient color 


Syntax 





void GsSetAmbient ( 
unsigned short r, 
unsigned short g, 


unsigned short b 


) 
Arguments 

r,g,b RGB values of the ambient color (0~4095) 
Explanation 





The ambient color is set to the RGB value specified by (r, g, b). 

The r, g, b arguments can pass values up to but not including 4096. 

A value of 4096 would represent a fixed point value of 1.0 and correspond to normal 
ambient brightness. A value of 0 corresponds to minimum brightness. A value of 1/8 of 


normal brightness would be specified with r, g, b values of 4096/8. 


Return Value 





None 


See also 





GsSetFlatLight() 
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GsSetClip 
Sets the clipping area for drawing 

Syntax 

void GsSetClip ( 

RECT *clip 

) 
Arguments 

clip Pointer to RECT structure defining the clipping area 
Explanation 





The clipping area defined by clip is set as the clipping area for drawing. 

This function is different from GsSetDrawBuffClip() in that its argument can be 

used to specify a clipping area. Note that this clipping value is a relative one within 
the double buffer, and thus the clipping position will not change even when double 
buffers are swapped. 

The clipping area set by GsSetClip is valid only within the current drawing buffer and 
becomes invalid when the buffers are swapped using GsSwapDispBuff(). This is 
because GsSwapDispBuff() calls GsSetDrawBuffOffset() which sets the clipping area 
from the clip member in the global variable GDDRAWENV. This value is obtained from 
the global variable CLIP2. 


Return Value 





None 
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Notes 
This function does not execute correctly if it is called when GPU drawing is in 
progress. ResetGraph(1) should be used to terminate any current drawing process or 
DrawSync(0) should be used to wait until drawing is completed before this function is 
called. 

See Also 
GsSetDrawBuffClip() 
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GsSetClip2D 


Sets a 2-dimensional clipping area 


Syntax 





void GsSetClip2D ( 
RECT *rectp 


) 
Arguments 

rectp Pointer to a 2D clipping area 
Explanation 





The 2D area pointed to by rectp is set as the clipping area. 

The clipping area is not affected by double buffer swapping, so the same area is 
automatically clipped regardless of which buffer is active. 

GsSetDrawBuffClip() must be called in order for the clip area to take effect immediately. 


Otherwise, the setting becomes valid with the next frame. 


Return Value 





None 
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GsSetDrawBuffClip 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





See Also 





Sets the clipping area for drawing 


void GsSetDrawBuffClip ( void ) 


None 


The clipping area used in drawing is updated with the value that was set using 
GsClip2D(). 
The clipping value is relative within the double buffers. In other words, the clipping 


position does not change when the double buffers are swapped. 


None 


This function does not execute correctly if it is called when GPU drawing is in 
progress. ResetGraph(1) should be used to terminate any current drawing process or 
DrawSync(0) should be used to wait until drawing is completed before this function is 


called. 


GsSetClip2D(), GsSetClip() 


97 


EEE Graphics Library Functions 





GsSetDrawBuffOffset 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 
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Sets the drawing offset 


void GsSetDrawBuffOffset ( void ) 


None 


The drawing offset is updated using the value defined in the global variable 
POSITION. The drawing offset is used for double buffer swapping and can be managed 
by the GTE or the GPU. 

The drawing offset is a relative offset within the double buffer. The offset value is 
preserved even when double buffers are swapped. 

The third argument of GsInitGraph() determines whether the offset is managed by the 


GTE or the GPU. 


None 


This function does not execute correctly if it is called when GPU drawing is in 
progress. ResetGraph(1) should be used to terminate any current drawing process or 
DrawSync(0) should be used to wait until drawing is completed before this function is 


called. 
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See Also 





GsSetOrign(), GsSetOffset(), POSITION 
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GsSetFlatLight 


Sets a parallel light source 


Syntax 





void GsSetFlatLight ( 
unsigned short id, 


GsF_LIGHT */t 


) 
Arguments 

id Light source number (0,1,2) 

It Pointer to light source information 
Explanation 





The parallel light source specified by id is set according to the GsF_LIGHT 


information pointed to by /t. Up to three separate light sources can be set (id = 0, 1, 2). 


Return Value 








None 

Notes 
When the contents of the GsF_LIGHT structure are overwritten, the new values will 
not be reflected in the light source until GsSetFlatLight() is called. 

See Also 





GsF_LIGHT, GsSetAmbient() 
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GsSetFogParam 


Sets the fog parameter 


Syntax 





void GsSetFogParam ( 
GsFOGPARAM *fogparam 


) 
Arguments 

fogparam Pointer to a fog parameter structure 
Explanation 





The fog parameter is set according to the GFRFOGPARAM structure pointed to by 


fogparam. Fog is only effective if the light source mode is 1 (see GsSetLightMode()). 


Return Value 





None 


See Also 





GsFOGPARAM, GsSetLightMode() 
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GsSetLightMatrix 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Sets the light matrix 


void GsSetLightMatrix ( 


MATRIX *mp 
) 


mp Pointer to a local screen light matrix 


The local screen light matrix pointed to by mp is multiplied by the matrix of three light 
vectors and the result is set as the light matrix in GTE. 

The light matrix needs to be set in GTE prior to performing light source calculations. 
Depending on the type of model data, the GsSortObject4() function may perform light 
source calculation at the time of execution. In this case, the light matrix needs to be 
preset using GsSetLightMatrix(). 

The matrix mp specified as the argument to GsSetLightMatrix() is normally a local 


world matrix. 


None 


GsSortObject4(), GsGetLw() 
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GsSetLightMode 


Syntax 





Arguments 


Explanation 





Return Value 





Sets the default light source mode 


void GsSetLightMode ( 


unsigned short mode 


) 


mode Light source mode (0~1) 
0: normal lighting 


1: normal lighting with fog ON 


The default light source mode is set to the value specified by mode. 

The light source mode can also be set independently for each object using the attribute 
member of GSDOBJ2. Bit 5 of attribute determines whether the light source mode is set 
by the GSDOBJ2 attribute field or by the mode set with GsSetLightMode(). See the 


description of GsDOBJ2 for more information. 


None 
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GsSetLsMatrix 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Sets the local screen matrix 


void GsSetLsMatrix ( 


MATRIX *mp 
) 


mp Pointer to a local screen matrix 


The local screen matrix pointed to by mp is set as the local screen matrix in GTE. 
The local screen matrix in GTE needs to be set prior to performing perspective 


transformation using a function such as GsSortObject4(). 


None 


GsSortObject4(), GsGetLs() 
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GsSetOffset 


Sets the drawing offset 


Syntax 





void GsSetOffset ( 


int offx, 
int offv 
) 
Arguments 
offx Drawing offset X coordinate 
offy Drawing offset Y coordinate 
Explanation 





The value of the drawing offset is set to (offx, offy). 

GsSetOffset() differs from GsSetDrawBuffOffset() in that GsSetDrawBuffOffset() sets the 
offset to the value specified by the global variable POSITION, whereas GsSetOffset() 
sets the offset to the value specified by the argument. 

The value set by GsSetOffset() is temporary in that it does not update the global 
variable POSITION and is only valid within the current draw buffer. This is because 
when the double buffer is swapped, GsSwapDispBuff() calls GsSetDrawBuffOffset() 
which sets the offset from the global variable POSITION. This value remains valid 
until it is changed by GsSetOrigin(). 

The offset specified as an argument is a relative offset inside the double buffer. In other 
words, the offset is added to the double buffer base to calculate the drawing address. 
The third argument of GsInitGraph() determines whether the offset is managed by the 
GTE or the GPU. 
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Return 
Value 





Notes 





See Also 
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None 


This function does not execute correctly if it is called when GPU drawing is in 
progress. ResetGraph(1) should be used to terminate any current drawing process or 


DrawSync(0) should be used to wait until drawing is completed before this function is 


called. 


GsSetDrawBuffOffset() 
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GsSetOrign 


Sets the drawing offset of the screen origin 


Syntax 





void GsSetOrign ( 


int x, 
int y 
) 
Arguments 
x Screen origin position X 
y Screen origin position Y 
Explanation 





The screen origin specified by (x, y) is set as the drawing offset in the global variable 
POSITION. 

GsSetOrign() sets the drawing offset in the global variable POSITION but it does not 
set it in the GPU. In other words, the new offset will not take effect until a function 
such as GsSetDrawBuffOffset() that sets the GPU drawing offset is called. 

The offset value in the global variable POSITION is valid until GsSetOrgn() is called 
again. 

The offset specified by (x, y) is relative within the double buffer. In other words, the 
values (x, y) are added to the double buffer base. In reality, the offset is set by the offx 


and offy members of the global variable POSITION. 


107 


EEE Graphics Library Functions 





Notes 





The third argument of GsInitGraph() determines whether the offset is executed by GTE 


or by GPU and is specified using GSOFSGTE or GsOFSGPU, respectively. 


Return Value 





None 
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GsSetProjection 


Syntax 





Arguments 


Explanation 





Return Value 





Sets the projection distance 


void GsSetProjection ( 


unsigned short h 


) 


h Projection distance. 


The projection distance is set to h. The projection distance is the distance between the 
viewpoint and the projection plane. 

The size of the projection plane is specified by the (vres, yres) arguments to 
GsInitGraph(). This size is constant for a given resolution. This means that the field of 
view decreases as the projection distance is increased, and conversely, the field of view 
increases as the projection distance is decreased. 

As shown in the table below, the aspect ratio is a function of the screen resolution and 
may not always be | to 1. In particular, when the resolution is 640 x 240, the X 


coordinate should be scaled by 1/2 to compensate. 


640x480 640x240 320x240 





None 
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GsSetRefView2 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Sets the viewpoint position 


int GsSetRefView2 ( 


GsRVIEW2 *pv 
) 


py Pointer to viewpoint position information (reference type) 


The World Screen Matrix (WSMATRIX) is calculated using the viewpoint information 
pointed to by pv. 

Since WSMATRIX does not change unless the viewpoint is moved, this function need 
not be called for each frame. However, if the viewpoint is moved, GsSetRefView2() must 
be called for changes to be reflected in each frame. 

GsSetRefView2() should be called each frame if the GSRVIEW2 member super is set to 
anything other than WORLD. In this case, the viewpoint will move if the parameters of 
the parent coordinate system change even if the other viewpoint parameters have not 


changed. 


0 is returned if the viewpoint was successfully set, otherwise, 1 is returned. 


GsRVIEW2,GsWSMATRIX, GsSetView2() 
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GsSetView2 


Syntax 





Arguments 


Explanation 





Return Value 





Sets the viewpoint position 


int GsSetView2 ( 
GsVIEW2 *pv 


) 


py Pointer to viewpoint position information (matrix type) 


The World Screen (WS) matrix is directly set from the viewpoint information pointed to 
by pv. 

When GsSetRefView2() is used to determine the WS matrix from the viewpoint, errors 
may occur when the viewpoint is moved due to insufficient precision in the operation. 
For this reason it is usually better to use GsSetView2(). 

GsSetView2() should be called each frame if the GSRVIEW2 member super is set to 
anything other than WORLD. In this case, the viewpoint will move if the parameters of 
the parent coordinate system change even if the other viewpoint parameters have not 
changed. 

If GSIDMATRIX2 is used as the base matrix, then the aspect ratio of the screen will be 


adjusted automatically. 


0 is returned if the viewpoint was successfully set, otherwise, 1 is returned. 
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See Also 





GsVIEW2, GSWSMATRIX, GsSetRefView2() 
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GsSetWorkBase 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Sets the base address of the drawing command area 


void GsSetWorkBase ( 
PACKET *base_addr 


) 


base_addr pointer to the first PACKET of the drawing command area 


The address of the packet at the start of the drawing command work area is set to the 
address specified by base_addr. The drawing command work area is used by functions 
such as GsSortObject4() and GsSortSprite(). 

This function must be called at the start of processing for each frame. Base_addr 
should be set to the starting address of the packet area allocated by the user. 


Note that the type PACKET is defined as an unsigned char in libps.h. 


None 


GsSortObject4(), GsSortSprite(), GsSortFastSprite(), GsOUT_PACKET_P 
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GsSortBoxFill 


Enters a rectangle in an OT 


Syntax 





void GsSortBoxFill ( 
GsBOXF *bp, 
GsOT *otp, 


unsigned short pri, 


) 
Arguments 
bp Pointer to a rectangle descriptor 
otp Pointer to an ordering table 
pri Position in the ordering table 
Explanation 





The rectangle pointed to by bp is entered into the ordering table pointed to by otp at 


position pri. 


Return Value 





None 
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GsSortClear 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





void GsSortClear ( 


unsigned char r, 
unsigned char g, 
unsigned char b, 
GsOT *otp 

) 


r, g, b 


otp 


Enters a Clear Screen command in an OT 


Background color RGB values 


Pointer to an ordering table 


A Clear Screen command is entered at the beginning of the ordering table pointed to by 


otp. 


None 


GsSortClear() merely enters the Clear Screen command in the ordering table. The screen 


will not actually be cleared until GsDrawOTCỌ) is called. 
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GsSortFastSprite 


Enters a sprite in an OT 


Syntax 





void GsSortFastSprite( 
GsSPRITE *sp, 
GsOT *otp, 


unsigned short pri 





) 
Arguments 
sp Pointer to a sprite 
otp Pointer to an ordering table 
pri Position in the ordering table 


Explanation 


The sprite pointed to by sp is entered into the ordering table pointed to by otp. 

The parameters of the sprite, such as its display position, are provided by the members 
of GsSPRITE. 

pri is the priority (i.e. position) of the sprite in the ordering table. The highest priority 
is obtained by setting pri to 0. The lowest priority is determined by the size of the 
ordering table. If the value of pri is greater than the size of the ordering table, it is 
clipped to the maximum size. 

GsSortFastSprite() provides higher speed processing than GsSortSprite(), however, 
scaling and rotation cannot be used. The GSSPRITE members mx, my, scalex, scaley, 


and rotate are ignored. 
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Return Value 





None 


See Also 





GsSortSprite(), GSSPRITE 
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GsSortFixBg16 


Syntax 





Enters a background descriptor in an OT at high speed 


void GsSortFixBg16 ( 


GsBG *bg, 


unsigned long *work, 


GsOT *otp, 


unsigned short pri 


) 
Arguments 
bg Pointer to a background descriptor 
work Pointer to the work area (primitive area) initialized with 
GsInitFixBg16() 
otp Pointer to an ordering table 
pri Position in the ordering table 
Explanation 





The background image pointed to by bg is entered into the ordering table pointed to 


by otp at position pri. 


GsSortFixBg16() has the following features and restrictions: 
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BG rotation and scaling cannot be performed. 

Cell size is fixed (16x16). 

Only texture pattern color modes 4-bit and 8-bit are supported. 
Map size is optional. 


Scrolling is permitted in 1 pixel units. 
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Return Value 





See Also 





eOnly full screen mode is supported. 


This function uses the work area pointed to by work to store drawing primitives. The 


work area must be initialized in advance by GsInitFixBg16().The packet area set with 


GsSetWorkBase() is not used. 


None 


GsInitFixBg16() 
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GsSortGLine 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Enters a graded straight line in an OT 


void GsSortGLine ( 
GsGLINE *ip, 
GsOT *otp, 


unsigned short pri 


) 

Ip Pointer to a graded straight line descriptor 
otp Pointer to an ordering table 

pri Position in the ordering table 


The graded straight line pointed to by {p is entered into the ordering table pointed to 
by otp at position pri. 
GsSortGLine() handles straight lines and GsSortLine() handles single-color straight 


lines. 


None 


GsSortLine() 
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GsSortLine 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Enters a single-color straight line in an OT 


void GsSortLine ( 
GsLINE *Jp, 
GsOT *otp, 


unsigned short pri 


) 

Ip Pointer to a single-color straight line descriptor 
otp Pointer to an ordering table 

pri Position in the ordering table 


The single-color straight line pointed to by /p is entered into the ordering table 
pointed to by ofp at position pri. 
GsSortLine() handles single-color straight lines and GsSortGLine() handles straight 


lines with gradation. 


None 


GsSortGLine() 
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GsSortObject4 


Inserts an object in an OT 


Syntax 





void GsSortObject4 ( 
GsDOBJ2 *objp, 
GsOT *otp, 

long shift, 


u_long *scratch 


) 
Arguments 
objp Pointer to a GSDOBJ2 object 
otp Pointer to an ordering table 
shift Number of bits the Z value will be right-shifted when the 
object is entered in the ordering table. 
scratch Pointer to a scratchpad buffer 
Explanation 





Performs perspective transformation and light source calculation for the 3D object 
pointed to by objp. Generates drawing commands for the object and stores those 
commands at the packet area work base address, previously specified with 
GsSetWorkBase(). Z-sorts the drawing commands and enters them in the ordering 


table pointed to by otp, shifting the Z values by an amount specified by shift. 
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Return Value 





See Also 





The precision of Z may be adjusted using shift. The maximum size of the ordering table 
(i.e. its resolution) is 14 bits and is specified in the GsOT structure. The value of shift 
must be set so that the area allocated to the ordering table will not be exceeded when 
the object is entered. For example, if the size of the ordering table is 12 bits, the shift 
value must be set to 14-12, or 2. 

scratch is a pointer to the Scratchpad buffer which is used when automatic polygon 
subdivision is being performed on the object. The size of the Scratchpad buffer is 1024 
bytes. 

The Scratchpad allows access to the Data Cache on the R3000. Using the Cache 
provides much faster access than main memory RAM for time-critical operations such as 
polygon subdivision. The Scratchpad is memory-mapped from addresses 0x1F800000 
to Ox F8003FF. 

Automatic polygon subdivision is enabled by setting the appropriate bits in the 
attribute member of GSDOBJ2. Subdivision is enabled by ORing the attribute member 
with one of the macros ‘GSDIV1’ through ‘GsDIVS5’ which are defined in libps.h. For 
example, if GsDIV1 is specified, a single polygon will be divided into 4 segments of 2 
x 2. If GsDIVS is specified, a single polygon will be divided into 1024 segments of 32 


x32. 


None 


GsDOBJ2, GsSetWorkBase() 
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GsSortOt 


Syntax 





Arguments 





Explanation 


Return Value 





See Also 
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Inserts a source OT into a destination OT 


GsOT *GsSortOt ( 
GsOT *ot_src, 
GsOT *ot_dest 


) 
ot_src Pointer to source ordering table 
ot_dest Pointer to destination ordering table 


The source ordering table pointed to by ot_src is inserted into the destination 
ordering table pointed to by ot_dest. The typical Z value of the source ordering table 


used for the insertion operation is given by the point member of ot_src. 


ot_dest, the pointer to the combined ordering table is returned. 


GsOT 
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GsSortSprite 


Enters a sprite in an OT 


Syntax 





void GsSortSprite ( 
GsSPRITE *sp, 
GsOT *otp, 


unsigned short pri 


) 
Arguments 
sp Pointer to a sprite 
otp Pointer to an ordering table 
pri Position in the ordering table 
Explanation 





The sprite pointed to by sp is entered into the ordering table pointed to by otp. 

The parameters of the sprite, such as its display position, are provided by the members 
of GsSPRITE. 

pri is the priority (i.e. position) of the sprite in the ordering table. The highest priority 
is obtained by setting pri to 0. The lowest priority is determined by the size of the 
ordering table. If the value of pri is greater than the size of the ordering table, it is 


clipped to the maximum size. 


Return Value 





None 
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See Also 





GsOT, GsSPRITE, GsSortFastSprite() 
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GsSwapDispBuff 


Syntax 





Swaps double buffers 


void GsSwapDispBuff ( void ) 


Arguments 


None 


Explanation 





The display buffer and drawing buffer that were defined using GsDefDispBuff() are 


swapped. 


Swapping is usually performed immediately after the start of the vertical blanking 


interval. 


GsSwapDispBuff() performs the following functions: 


l. 
> 
3. 
4. 
5. 
6. 


Sets display starting address 
Cancels blanking 

Sets double buffer index 

Switches two-dimensional clipping 
Sets GTE or GPU offset 


Increments PSDCNT 


Note: Double buffering is implemented using an offset. The third argument of 


GsInitGraph() determines whether the offset is managed by the GTE or the GPU. 


Return Value 





None 
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Notes 
This function does not execute correctly if it is called when GPU drawing is in 
progress. ResetGraph(1) should be used to terminate any current drawing process or 
DrawSync(0) should be used to wait until drawing is completed before this function is 
called. 

See Also 
GsDefDispBuff() 
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gteMIMefunc 


Syntax 





Arguments 


Explanation 





Adds a vertex data vector to a differential data vector multiplied 
by a control coefficient 


void gteMIMefunc ( 
SVECTOR *otp, 
SVECTOR *dfp, 
long n, 

long p 

) 


otp Pointer to vertex data vector (input/output) 
dfp Pointer to differential data vector (input) 
n Number of vertices (differentials) 


p MIMe weight (control) coefficient 


The vertex data vector otp is added to the product of the differential data vector dfp and 
the MIMe control coefficient p, and the result is stored back in the vertex data vector 
otp. 

p is considered to be a 12-bit integer.This following program fragment illustrates the 
algorithm that is used. 

void gteMIMefunc(SVECTOR *otp, SVECTOR *dfp, long n, long p) 

{ 


int i; 
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for(i=0;i<n 
(otp 


(otpṣ 


3 i++){ 


Hi)>x += ( (int)((dfp 
H)->y += ((int)((dfpti)-y) * p P>12; 





(otp1 


} 


The argument format is as follows:: 
p:(,19,12) 


otp, dfp arbitrary 


Return Value 


None 
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Hi)->x) * p )>>12; 





= ((int((dfp 


Hi)->z) * p )>>12; 
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KanjiFntClose 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





Closes a print stream 


int KanjiFntClose( void ) 


None 


All streams currently open and used by KanjiFntPrint() are initialized and cleared. 


None 


Since KanjiFntClose() only initializes the internal state, this function completes even 


when there is no stream open. 
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KanjiFntFlush 


Draws the contents of a print stream 


Syntax 





u_long *KanjiFntFlush ( 


int id 

) 
Arguments 

id Print Stream ID 
Explanation 





The contents of the specified print stream are drawn in the frame buffer. KanjiFntFlush() 
initializes and draws a sprite primitive list corresponding to the characters in the 


specified print stream. 


Return Value 





A pointer to the start of the ordering table used for drawing is returned. 


Notes 





After drawing is completed, the contents of the print stream are flushed. 
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KanjiFntOpen 


Syntax 





Arguments 


int KanjiFntOpen ( 
int x, 
int y, 
int w, 
int A, 
int dx, 
int dy, 
int cx, 
int cy, 
int isbg, 
int n 


) 


xX, y 
w, h 
dx,dy 
cx,cy 


isbg 


Opens a print stream 


Display start positions 

Display area 

Kanji font pattern frame buffer address 

Kanji CLUT frame buffer address 

Background auto-clear flag 
0: Clear the background to (0,0,0) when displaying. 
1: Do not clear the background. 


Maximum number of characters that can be drawn 
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Explanation 





The stream used for on-screen printing is opened. Subsequently, character strings up to 
n characters long can be drawn in the rectangular area of the frame buffer specified by 
(x,y)-(xt+w, y+h) using the KanjiFntPrint() function. 


Ifisbg has a value of “1”, the background is cleared when a character string is drawn. 


Return Value 





The ID of the print stream that was opened is returned. 


Notes 





Up to 8 streams can be opened simultaneously. 
Opened streams cannot be closed until the next KanjiFntLoad(). 


The Kanji font area must not overlap with the frame buffer area used by the application. 
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KanjiFntPrint 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





Sends output to a print stream 


int KanjiFntPrint( 
int id, 


char *format, 


) 
id Print stream ID 
format Print format 


The SHIFT-JIS full-width character string specified as an argument is formatted and sent 
as output to the specified print stream. Formatting is performed according to the format 
string and is identical to the specification of the format string for the C library fprintf() 


function. 


The number of characters in the stream is returned. 


The Kanji code must be SHIFT-JIS. Full-width and half-width characters can be mixed 
in the character string, but they are all changed to full-width at the time of display. 
Half-width kana are not supported. The character string is not displayed until 


KanjiFntFlush() is executed. 
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Krom2Tim 


Converts a SHIFT-JIS character string to 4-bit CLUT TIM data 


Syntax 





int Krom2Tim( 
u_char *sjis, 
u_long *taddr, 
int dx, 

int dy, 

int cx, 

int cy, 

u_int fg, 

u_int bg 


) 


Arguments 
sjis SHIFT-JIS Character String 
taddr Pointer to TIM data result storage area 
dx, dy x,y coordinates of pixel data in VRAM 
CX, CY x,y coordinates of CLUT data in VRAM 


fg, bg Foreground and background colors 


Explanation 





The SHIFT-JIS character string specified by sjis is converted to 4-bit CLUT TIM data. 


The result is placed in the buffer pointed to by taddr. 
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Return Value 





0 is returned when conversion is successful. -1 is returned when the code specified by 


sjis is invalid. 


Notes 





The Kanji code must be SHIFT-JIS encoded. Full-width and half-width characters can 
be mixed in the character string, but they are all changed to full-width at the time the 
characters are displayed. Half-width kana are not supported. 

For the area specified by taddr, the size shown in the following formula must be 


allocated in advance. 


128 x (length of character string specified by sjis) + 84(bytes) 
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Krom2Tim2 


Converts a SHIFT-JIS character string to 4-bit CLUT TIM data 


Syntax 





int Krom2Tim2( 
u_char *sjis, 
u_long *taddr, 
int dx, 

int dy, 

int cdx, 

int cdy, 

u_int fg, 

u_int bg 


) 


Arguments 


sjis SHIFT-JIS Character String 

taddr Pointer to TIM data result storage area 
dx, dy x,y coordinates of pixel data in VRAM 
CX, CY x,y coordinates of CLUT data in VRAM 


fg, bg Foreground and background colors 


Explanation 





The SHIFT-JIS character string specified by sjis is converted to 4-bit CLUT TIM data. 
The result is placed in the buffer pointed to by taddr. Krom2Tim2() is the user-defined 


character version of Krom2Tim(). 
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Return Value 





0 is returned when conversion is successful. -1 is returned when the code specified by 


sjis is invalid. 


Notes 





The Kanji code must be SHIFT-JIS encoded. Full-width and half-width characters can 
be mixed in the character string, but they are all changed to full-width at the time the 
characters are displayed. Half-width kana are not supported. 
For the area specified by taddr, the size shown in the following formula must be 
allocated in advance, where num is the length of the string specified by sjis. 
If num<16) 
(32 * num + 16) * 4 (bytes) 


else 
(32 * 16* (((num-1)/16 + 1) +16) * 4 (bytes) 
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LoadImage 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 
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Transfers image data from memory to the frame buffer 


int LoadImage ( 


RECT *recp, 

u_long *p 

) 

recp Pointer to the destination rectangular area in the frame buffer 
p Pointer to the source area in main memory 


Data from the source area in main memory pointed to by p is transferred to the 


rectangular area of the frame buffer pointed to by recp. 


The slot number of the GPU’s draw/command queue where the command resides is 


returned. 


LoadImage() is a non-blocking function, therefore DrawSync() must be used to 
determine the completion of transfer. 

The transfer is not affected by clipping or offsetting that may be in effect for the drawing 
environment. 

The transfer area must be located within a drawable area: (0,0) - (1023,511). 
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MovelImage 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





int MoveImage ( 
RECT *recp, 

int x, 

int y 


) 


recp 


x,y 


Transfers data within the frame buffer 


Pointer to source rectangle in the frame buffer 
Pointer to upper left-hand corner of the destination rectangle in 


the frame buffer 


The rectangular area in the frame buffer specified by recp is transferred to a rectangular 


area of the same size starting at location x,y in the frame buffer. 


The slot number of the GPU’s draw/command queue where the command resides is 


returned. 


Movelmage() is a non-blocking function, therefore DrawSync() must be used to 
determine the completion of transfer. 
The transfer is not affected by clipping or offsetting that may be in effect for the drawing 


environment. 


The transfer area must be located within a drawable area: (0,0) - (1023,511). 
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The contents of the source are unaffected by the transfer. If the source and destination 


areas are the same, the results are unpredictable. 
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MulMatrix0 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





Multiplies two matrices 


MATRIX* MulMatrix0 ( 
MATRIX *m0, 
MATRIX *m/]1, 


MATRIX *m2 
) 


m0,m1 Pointers to input matrices 


m2 Pointer to result matrix 


Matrix m0 is multiplied by matrix m/ and the result is stored in matrix m2. 
The argument format is as follows:: 


mOym1,m2->m{i][j] : (1,3,12) 


The matrix product m2 is returned. 


This function destroys the rotation matrix. 
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PopMatrix 


Syntax 


Arguments 


Explanation 


Return Value 
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Pops the rotation matrix off the stack 


void PopMatrix ( void ) 


None 


The rotation matrix is popped off the stack. 


None 
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PushMatrix 
Pushes the rotation matrix onto the stack 
Syntax 
void PushMatrix ( void ) 
Arguments 
None 
Explanation 





The rotation matrix is pushed onto the stack. The stack has a maximum of 20 slots. 


Return Value 


None 
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PutDispEnv 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





See Also 
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Sets the display environment 


DISPENV *PutDispEnv ( 


DISPENV *env 
) 


env 


Pointer to the display environment 


The basic parameters of the display environment are established according to the 


display environment pointed to by env. The display environment becomes effective 


immediately when the function is called. 


A pointer to the new display environment is returned if the function succeeded. “0” is 


returned if PutDispEnv failed to set the new display environment. 


The drawing environment specified by PutDispEnv() is valid until the next call to 


PutDispEnv() or GsSwapDispBuff(). 


GsSwapDispBuff(), DISPENV 
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PutDrawEnv 


Sets the drawing environment 


Syntax 





DRAWENV *PutDrawEnv ( 


DRAWENV “*env 


) 
Arguments 

env Pointer to the drawing environment 
Explanation 





The basic parameters of the drawing environment (e.g. drawing offset and drawing clip 


area) are established according to the drawing environment pointed to by env. 


Return Value 





A pointer to the new drawing environment is returned if the function succeeded. “0” 


is returned if PutDrawEnv() failed to set the new drawing environment. 


Notes 





The drawing environment specified by PutDrawEnv() is valid until the next call to 


PutDrawEnv() or GsSwapDispBuff(). 


See Also 





GsSwapDispBuff), DRAWENV 


147 


EEE Graphics Library Functions 








ResetGraph 
Initializes the graphics system 
Syntax 
int ResetGraph ( 
int mode 
) 
Arguments 
mode Specifies the reset mode as indicated below. 
0: Full reset. The drawing environment and display 
environment are initialized. 
1: The current drawing is cancelled and the command queue 
is flushed. 
Explanation 





The graphics system is reset with the mode specified by mode. 


Return Value 





None 
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RotMatrix 


Syntax 





Arguments 


Explanation 





Calculates a rotation matrix from a rotation vector 


MATRIX* RotMatrix ( 


MATRIX *m 

SVECTOR *r 

) 

m Pointer to output rotation matrix 
r Pointer to input rotation vector 


The rotation matrix m is calculated from the rotation vector (r->vx,r->vy,r->vz). In the 
rotation vector, 360° is represented as 4096, and 4096 is equivalent to 1.0 in each 
element. 


The matrix is an expansion of the following product. 


Using GTE coordinate transformation, the vectors are multiplied from the right. Thus 
the matrix rotates around the Z, Y and X axes in that order. 

Angle value 

c0=cos(r->vx), sO=sin(r->vx) 

cl=cos(r->vy), s1=sin(r->vy) 


c2=cos(r->vz), S2=sin(r->vz) 
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The argument format is as follows:: 
m->m{i]{j] : (1,3,12) 
r->VxX,Vy,vz :(1,3,12) (however 360° is 1.0) 


Return Value 





The rotation matrix m is returned. 
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RotMatrixX 


Rotates a matrix around the X-Axis 


Syntax 





MATRIX* RotMatrixX ( 


long r, 

MATRIX *m 

) 
Arguments 

r Input rotation amount 

m Pointer to the matrix (used for both input and result) 
Explanation 





The matrix m is rotated around the X-axis by an amount specified by r. In the rotation 


amount, 360° is represented as 4096, and 4096 is equivalent to 1.0. 


The matrix is calculated as follows:: 


* c=cos(r), s=sin(r) 
The argument format is as follows:: 
m->m[i]{j] : (1,3,12) 
r:(1,3,12) (however 360° is equivalent to 1.0) 


Return Value 





The rotated matrix m is returned. 
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RotMatrixY 


Rotates a matrix around the Y-Axis 


Syntax 





MATRIX* RotMatrixY ( 


long r, 

MATRIX *m 

) 
Arguments 

r Input rotation amount 

m Pointer to the matrix (used for both input and result) 
Explanation 





The matrix m is rotated around the Y-axis by an amount specified by r. In the rotation 


amount, 360° is represented as 4096, and 4096 is equivalent to 1.0. 


The matrix is calculated as follows:: 


* c=cos(r), s=sin(r) 
The argument format is as follows:: 
m->m{[i]fj] : (1,3,12) 
r:(1,3,12) (however 360° is 1.0) 


Return Value 





The rotated matrix m is returned. 
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RotMatrixZ 
Rotates a matrix around the Z-Axis 

Syntax 

MATRIX* RotMatrixZ ( 

long r, 

MATRIX *m 

) 
Arguments 

r Input rotation amount 

m Pointer to the matrix (used for both input and result) 
Explanation 





The matrix m is rotated around the Z-axis by the amount specified by r. In the rotation 


amount, 360° is represented as 4096, and 4096 is equivalent to 1.0. 


The matrix is calculated as follows:: 


* c=cos(r), s=sin(r) 
The argument format is as follows:: 
m->m{i]{j] : (1,3,12) 


r:(1,3,12) (however 360° is 1.0) 


Return Value 





The rotated matrix m is returned. 
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ScaleMatrix 


Scales a matrix 


Syntax 





MATRIX* ScaleMatrix ( 


MATRIX*m, 
VECTOR*v 
) 
Arguments 
m Pointer to matrix (both input and result) 
v Pointer to scale vector 
Explanation 





The matrix m is scaled by an amount specified by the scale vector v. Each element of v is 


an integer with 4096 equivalent to 1.0. 


If m= v= 


then m= 


The argument format is as follows:: 
m->mfiJ[j] : (1,3,12) 


y->vx,vy,vz : (1,19,12) 
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Return Value 





The scaled matrix m is returned. 
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ScaleMatrixL 


Scales a matrix 


Syntax 





MATRIX* ScaleMatrixL ( 


MATRIX*m, 
VECTOR*v 
) 
Arguments 
m Pointer to matrix (both input and result) 
v Pointer to scale vector 
Explanation 





The matrix m is scaled by an amount specified by the scale vector v. Each element of v is 


an integer with 4096 equivalent to 1.0. 


Ifm = v= 


then m= 


The argument format is as follows:: 
m->m{[i]lj] : (1,3,12) 


v->vx,vy,vz : (1,19,12) 
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Return Value 





The scaled matrix m is returned. 
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SetDispMask 


Sets the display mask 


Syntax 





void SetDispMask( 


int mask 
) 
Arguments 
mask 0: Inhibits screen display. 
l: Enables screen display. 
Explanation 





The display is turned on or off according to the value of mask. 


Return Value 





None 
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StoreImage 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





Transfers image data from the frame buffer to memory 


int Storelmage ( 


RECT *recp, 

u_long *p 

) 

recp Pointer to the source rectangular area in the frame buffer 
p Pointer to the upper left-hand corner of the destination 


rectangular area in main memory 


Data from the rectangular area pointed to by recp is transferred to the destination 


rectangular area in main memory pointed to by p. 


The slot number of the GPU’s draw/command queue where the command resides is 


returned. 


StoreImage() is a non-blocking function, therefore DrawSync() must be used to 
determine the completion of transfer. 

The transfer is not affected by clipping or offsetting that may be in effect for the drawing 
environment. 

The transfer area must be located within a drawable area: (0,0) - (1023,511). 
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TransMatrix 


Translates a matrix 


Syntax 





MATRIX* TransMatrix ( 


MATRIX*m, 
VECTOR*v 
) 
Arguments 
m Pointer to the matrix (used for both input and result) 
v Pointer to the translation vector 
Explanation 





The matrix m is translated by an amount specified by the translation vector v. 
The argument format is as follows:: 

m->m[i]fj] : (1,3,12) 

m->t[i]: (1,31,0) 


v->vx,vy,vz : (1,31,0) 


Return Value 





The translated matrix m is returned. 
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TransposeMatrix 


Transposes a matrix 


Syntax 





MATRIX* TransposeMatrix ( 


MATRIX*m0 
MATRIX*m/ 
) 
Arguments 
m0 Pointer to input matrix 
ml Pointer to result matrix 
Explanation 





The transpose of matrix m0 is calculated and the result is placed in matrix m1. 
The argument format is as follows:: 

m0->m[i][j] : (1,3,12) 

ml->m[i][j] : (1,3,12) 


Return Value 





The transposed matrix m1 is returned. 
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VSync 


Syntax 





Arguments 


Explanation 





Return Value 
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Waits for next vertical synchronization period 


int VSyne( 
int mode 


) 


mode 0: Blocks until vertical synchronization occurs. 
1: Returns the elapsed time in HSync units from the last call to VSync(). 
n: (n>1) Blocks for n VSync periods from the last call to VSync(). 


n: (n<0) Returns absolute time from program start in VSync units. 


Vsync() waits for the start of the next vertical synchronization interval. 


mode>=0 The elapsed time since the last call to VSync() is returned 
in HSync units. 
mode<0 The absolute time since program start is returned in VSync 


units. 
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VSyncCallback 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





Defines a function to be executed during each VSync period 


int VSyncCallback( 
void (*func)() 
) 


func Pointer to the callback function (function to be executed). 


Specifies that the function func will be called at the start of the vertical 
synchronization period. 
When func is “0”, any function previously registered as a callback function is 


removed. 


None 


Subsequent interrupts will be masked within func. Therefore, it is necessary to return 
quickly after func is called. 
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SndVolume 
Volume 
Structure 
struct SndVolume { 
unsigned short left; 
unsigned short right; 
bs 
Members 
left Left channel volume value 
right Right channel volume value 
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SsGetMute 


Gets mute state 


Syntax 





char SsGetMute ( void ) 


Explanation 


The current mute state is obtained and returned. 


Return Value 





The mute state is returned as indicated below. 
SS_MUTE_ ON Mute on 
SS_MUTE_OFF Mute off 


See Also 





SsSetMute() 
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SsGetMVol 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Gets the main volume 


void SsGetMVol ( 


SndVolume *m_vol 


) 


m_vol Pointer to SndVolume structure for storing result 


The value of the main volume is obtained and placed in the SndVolume structure 


pointed to by m_vol. 


None 


SsSetMVol() 
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SsGetSerialAttr 
Gets the value of a CD audio attribute 
Syntax 
char SsGetSerialAttr ( 
char s_num, 
char attr 
) 
Arguments 
s num Must be set to SS_CD 
attr Attribute to be obtained 
attr =SS_MIX Mixing 
attr =SS_REV Reverberation 
Explanation 





Return Value 





See Also 





The value of the CD audio attribute specified by attr is obtained and returned. 


1 is returned if the specified attribute is on and 0 is returned if off. 


SsSetSerialAttr() 
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SsGetSerialVol 


Gets CD audio volume 


Syntax 





void SsGetSerialVol ( 
char s_num, 


SndVolume *s_vol 


) 
Arguments 

s num Must be set to SS_CD 

s_vol Pointer to SndVolume structure for storing result 
Explanation 





The current CD audio volume value is placed in the structure pointed to by s_vol. 


Return Value 





None 


See Also 





SsSetSerialVol() 
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SsIsEos 


Syntax 





Arguments 


Explanation 





Return Value 





Returns the playback state of a song 


short SsIsEos ( 
short access_num, 


short seq_num 


) 
access_num SEQ access number 
seq num Must be set to 0 


The playback state of the song specified by access_num is obtained and its value is 


returned. 


1 is returned if the song is being played, otherwise 0 is returned. 
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SsPlayBack 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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void SsPlayBack ( 
short access_num, 
short seq_num, 


short /_count 


) 


access _num 
seq num 


l count 


Plays back SEQ data 


SEQ access number 
Must be set to 0 


Song repetition count 


The song which is currently playing is interrupted and the song which is specified by 


access_num is played. 


The song repetition count is specified in / count. If]_count is set to 


SSPLAY_INFINITY, the song will play continuously. 


None 


SsSeqPlay() 
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SsSeqClose 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Closes SEQ data 


void SsSeqClose ( 


short seq_access_num 


) 


seq_access_num SEQ access number 


The SEQ data specified by seq_access_num is closed. 


None 


SsSeqOpen() 
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SsSeqGetVol 
Gets SEQ volume 

Syntax 

void SsSeqGetVol ( 

short access_num, 

short seq_num, 

short *voll, 

short *volr 

) 
Arguments 

access_num SEQ access number 

seg num Must be set to 0 

voll Pointer to SEQ left volume result value 

volr Pointer to SEQ right volume result value 
Explanation 





The current left and right volume values of the song specified by access_num are 


obtained and placed at the storage locations pointed to by voll and volr, respectively. 


Return Value 





None 


See Also 





SsSeqSetVol() 
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SsSeqOpen 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Opens SEQ data 


short SsSeqOpen ( 
unsigned long* addr, 
short vab_id 


) 


addr Pointer to start of SEQ data in main memory 


vab_id VAB ID 


The SEQ data beginning at the area in memory pointed to by addr and having the 
specified vab_id is opened and its SEQ access number is returned. 
If an attempt is made to open more than 32 SEQ data groups, the function fails and a 


value of -1 is returned. 


The SEQ access number is returned if the SEQ data was successfully opened. -1 is 


returned if an error occurred. 


SsSeqClose() 
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SsSeqPause 


Pauses the playback of SEQ data 


Syntax 





void SsSeqPause ( 


short seq_access_num 


) 
Arguments 

seq_access_num SEQ access number 
Explanation 





The playback of the song specified by seg_access_num is paused. 


Return Value 


None 


See Also 





SsSeqPlay(), SsSeqReplay() 
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SsSeqPlay 





Syntax 
void SsSeqPlay ( 
short seq_access_num, 
char play_mode, 
short /_count 
) 
Arguments 
seq_access num 
play_mode 
l count 
Explanation 





Plays SEQ data 


SEQ access number 

Playback mode 
SSPLAY PAUSE Pause immediately before playing 
SSPLAY_ PLAY Begin playing immediately 


Song repetition count 


The song specified by seg_access_num is played according to the specified playback 


mode. 


The song repetition count is specified by /_count. If l_count is set to 


SSPLAY_INFINITY, the song will loop continuously. 


If play_mode is set to SSPLAY_ PAUSE, the song will be held in pause state until it 


is released. If play_mode is set to SSPLAY_ PLAY, the song will begin playing 


immediately. 
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Return Value 





None 


See Also 





SsSeqPause(), SsPlayBack(), SsSeqStop() 
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SsSeqReplay 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Resumes playback of SEQ data 


void SsSeqReplay ( 


short seq_access_num 


) 


seq_access_num SEQ access number 


The playback of the song specified by seq_access_num, which is currently paused, is 
resumed. 
SsSeqReplay() can be used to continue playing a song that was previously paused 


with SsSeqPause() or SsSeqPlay(). 


None 


SsSeqPlay(), SsSeqPause() 
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SsSeqSetAccelerando 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Accelerates the tempo 


void SsSeqSetAccelerando ( 
short seq_access_num, 
long tempo, 


long v_time 


) 

seq _access_num SEQ access number 
tempo Tempo 

v_time Time (in ticks) 


The tempo of the song specified by seg_access_num is incrementally increased to the 
value specified by tempo in the amount of time specified by v_time. 

v_time is specified in number of ticks where 1 tick = 1/60 sec. SsSeqSetAccelerando() 
gradually increases the tempo to the specified tempo. v_time indicates how long it 


will take to reach that tempo. 


None 


SsSeqSetRitardando() 
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SsSeqSetNext 


Links SEQ data for playback 


Syntax 





void SsSeqSetNext ( 
short seq_access_num1, 


short seq_access_num2 


) 
Arguments 
seq_access_num1 SEQ access number 
seq_access_num2 SEQ access number 
Explanation 





The SEQ data specified by seq_access_num2 is linked to the SEQ data specified by 
seq_access_num1. This will cause the song specified by seg_access_num?2 to be 


played immediately after the song specified by seq_access_num1. 


Return Value 





None 


181 


M88 Sound Library Functions 





SsSeqSetRitardando 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Slows the tempo 


void SsSeqSetRitardando ( 
short seq_access_num, 
long tempo, 


long v_time 


) 

seq _access_num SEQ access number 
tempo Tempo 

v_time Time (in ticks) 


The tempo of the song specified by seg_access_num is incrementally decreased to the 
value specified by tempo in the amount of time specified by v_time. 

v_time is specified in number of ticks where 1 tick = 1/60 sec. SsSeqSetRitardando() 
gradually decreases the tempo to the specified tempo. v_time indicates how long it 


will take to reach that tempo. 


None 


SsSeqSetAccelerando() 
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SsSeqSetVol 


Sets SEQ volume 


Syntax 





void SsSeqSetVol ( 


short seq_access_num, 


short voll, 

short volr 

) 
Arguments 

seq_access_num SEQ access number 

voll Left channel main volume 

volr Right channel main volume 
Explanation 





The main volume of the song specified by seg_access_num is set to the values 


specified by voll (left) and vo/r (right). The volume values can range from 0 to 127. 


Return Value 





None 


See Also 





SsSeqGetVol() 
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SsSeqStop 


Syntax 





Arguments 


Explanation 





Return Value 


See Also 
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Ends playback of SEQ data 


void SsSeqStop ( 


short seq_access_num 


) 


seq_access_num SEQ access number 


The playback of the song specified by seq_access_num is ended. 


None 


SsSeqPlay() 
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SsSetMute 


Sets or clears the mute state 


Syntax 





void SsSetMute ( 


char mode 
) 
Arguments 
mode Mute mode 
SS_MUTE_ON Mute on 
SS_MUTE_ OFF Mute off 
Explanation 





The mute state is set to the mode specified by mode. 


Return Value 


None 


See Also 





SsGetMute() 
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SsSetMVol 
Sets the main volume 

Syntax 

void SsSetMVol ( 

short voll, 

short volr 

) 
Arguments 

voll Left channel volume 

volr Right channel volume 
Explanation 





The main volume is set to the values specified by voll (left) and volr (right). Volume 
values can range from 0 to 127. 


The main volume must be set before playing a song. 


Return Value 





None 


See Also 





SsGetMVol() 
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SsSetSerialAttr 


Syntax 





Arguments 


Explanation 


Return Value 





See Also 





Sets CD audio attribute 


void SsSetSerialAttr ( 


char s_num, 
char attr, 
char mode 
) 
s num Must be set to SS_CD 
attr Attribute 
attr =SS_MIX Mixing 
attr =SS_REV Reverberation 
mode Desired mode 
mode =SS_SON Set attribute on 
mode = SS_SOFF Set attribute off 


The CD audio attribute specified by attr is set according to the value of mode. 


None 


SsGetSerialAttr() 
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SsSetSerialVol 


Set CD audio volume 


Syntax 





void SsSetSerialVol ( 


short s_num, 


short voll, 
short volr 
) 
Arguments 
s num Must be set to SS_CD 
voll Left channel volume 
volr Right channel volume 
Explanation 





The CD audio volume is set to the values specified by voll (left) and volr (right). 


Volume values can range from 0 to 127. 


Return Value 





None 


See Also 





SsGetSerialVol() 
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SsSetTempo 


Syntax 





Arguments 


Explanation 





Return Value 





Sets the tempo 


void SsSetTempo ( 
short access_num, 
short seq_num, 


short tempo 


) 

access_num SEQ access number 
seg num Must be set to 0 
tempo Song tempo 


The tempo of the song specified by access_num is set to the value specified by tempo. 
SsSetTempo() can be used to change the tempo set by SsSeqPlay(). The new tempo will 


take effect immediately. 


None 
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SsUtAllKeyOff 


Syntax 


void SsUtAllKeyOff ( 


short mode 


) 
Arguments 

mode Must be 0 
Explanation 

Forcibly keys off all voices. 
Return Value 


None 


See Also 


SsUtKeyOn(), SsUtKeyOffQ), SsSeqPlay() 
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SsUtChangePitch 


Syntax 





Arguments 


Explanation 





Changes the pitch 


short SsUtChangePitch ( 


short voice, 
short vabld, 
short prog, 
short old_note, 
short old_fine, 
short new_note, 


short new_fine 


) 


voice 
vabld 
prog 
old_note 
old_fine 
new_note 


new_fine 


Voice number 

VAB ID 

Program number 

Note number passed to SsUtKeyOn() 

Fine pitch passed to SsUtKeyOn() (note number) 
Updated note number 


Updated pitch 


The pitch of the voice keyed on by SsUtKeyOn() is changed according to the values 


specified by new_note and new_fine. 
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Return Value 





0 is returned if the pitch was successfully changed, otherwise -1 is returned. 


See Also 





SsUtPitchBend() 
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SsUtGetReverbType 


Gets the reverberation type 


Syntax 





short SsUtGetReverbType ( void ) 


Arguments 


None 


Explanation 





The value of the current reverberation type is obtained and returned. 


Return Value 





The value of the current reverberation type is returned. 


See Also 





SsUtSetReverbType() 
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SsUtGetVVol 


Gets voice volume 


Syntax 





short SsUtGetVVol ( 
short vc, 
short *voll, 


short *volr 


) 
Arguments 
ve Voice number 
voll Pointer to memory area for storing result volume (left) 
volr Pointer to memory area for storing result volume (right) 
Explanation 





The values of the volume specified by vc are obtained and placed in the storage 


locations specified by voll (left) and vo/r (right). 


Return Value 





0 is returned if the values were successfully obtained, otherwise -1 is returned. 


See Also 





SsUtSetVVol() 
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SsUtKeyOff 


Syntax 





short SsUtKeyOff ( 
short voice, 

short vabld, 

short prog, 

short tone, 


short note 


) 
Arguments 

voice 

vabld 


prog 
tone 


note 


Explanation 





Keys off voice 


Voice number 
VAB ID 
Program number 
Tone number 


Pitch specification (note number) in half tones 


The voice that was keyed on by SsUtKeyOn() is keyed off. 


Return Value 





0 is returned if the voice was successfully keyed off, otherwise -1 is returned. 


See Also 





SsUtKeyOn(), SsUtAlIKeyOffO 
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SsUtKeyOn 


Keys on voice 


Syntax 





short SsUtKeyOn ( 


short vabld, 


short prog, 

short tone, 

short note, 

short fine, 

short voll, 

short volr 

) 
Arguments 

vabld VAB ID 

prog Program number 

tone Tone number 

note Pitch specification (note number) in half tones 

fine Fine pitch (100/127 cents) 

voll Volume (left) 

volr Volume (right) 
Explanation 





The voice specified by the vabid, prog, and other arguments is keyed on at the 
specified pitch and volume. The allocated voice number is returned. 
note specifies the actual key that will be played and represents one of the 128 keys on 


the piano. fine specifies the pitch of that note. 
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Return Value 





If the function is successful, the allocated voice number (0 to 23) is returned. 


-1 is returned if the key on failed to complete. 


See Also 





SsUtKeyOff(), SsUtAlIKeyOff() 
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SsUtPitchBend 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Applies a pitch bend 


short SsUtPitchBend ( 
short voice, 


short vabld, 


short prog, 

short note, 

short pbend 

) 

voice Voice number 

vabld VAB ID 

prog Program number 

note Pitch specification (note number) in half tones. 
pbend Pitch bend value 


The pitch bend specified by pbend is applied to the voice keyed on by SsUtKeyOn(). 


0 is returned if the pitch bend was successfully applied, otherwise -1 is returned. 


SsUtChangePitch() 
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SsUtReverbOff 


Turns off reverberation 


Syntax 





void SsUtReverbOff ( void ) 


Arguments 


None 


Explanation 





Reverberation is turned off. 


Return Value 


None 


See Also 





SsUtReverbOn() 
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SsUtReverbOn 


Turns reverberation on 


Syntax 





void SsUtReverbOn ( void ) 


Arguments 


None 


Explanation 





Reverberation is turned on using the type and depth previously set with 


SsUtSetReverbType() and SsUtSetReverbDepth(). 


Return Value 





None 


See Also 





SsUtReverbOff() 
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SsUtSetReverbDelay 


Sets the amount of reverberation delay 


Syntax 





void SsUtSetReverbDelay ( 


short delay 


) 
Arguments 

delay Reverberation delay amount (0~127) 
Explanation 





The amount of reverberation delay is set to the value specified by delay. 


Reverberation delay applies only to echo-type and delay-type reverberation. 


Return Value 





None 


See Also 





SsUtSetReverbType() 
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SsUtSetReverbDepth 


Sets the reverberation depth 


Syntax 





void SsUtSetReverbDepth ( 
short /depth, 


short rdepth 


) 
Arguments 
Idepth Left reverberation depth value (0~127) 
rdepth Right reverberation depth value (0~127) 
Explanation 





The reverberation depth is set to the values specified by /depth (left) and rdepth 








(right). 
Return Value 
None 
See Also 
SsUtSetReverbType() 
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SsUtSetReverbFeedback 


Sets the amount of reverberation feedback 





Syntax 

void SsUtSetReverbFeedback ( 

short feedback 

) 
Arguments 

feedback Amount of reverberation feedback (0~127) 
Explanation 





The amount of reverberation feedback is set to the value specified by feedback. 


Reverberation feedback applies only to echo-type reverberation. 


Return Value 





None 


See Also 





SsUtSetReverbType() 
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SsUtSetReverbType 


Sets the reverberation type 


Syntax 





short SsUtSetReverbType ( 


short type 
) 
Arguments 
type Reverberation type 


Delay time * Feedback* 


SS_REV_TYPE_ROOM Room 


SS_REV_TYPE STUDIO_A 
SS_REV_TYPE STUDIO B 
SS_REV_TYPE STUDIO. C 
SS_REV_TYPE HALL 
SS._REV_ TYPE SPACE 
SS_REV_TYPE_ ECHO 
SS_REV_TYPE DELAY 
SS_REV_TYPE PIPE x 


* Delay time and feedback amount can also be set 














Explanation 





The reverberation type specified by type is set. When the reverberation type is set, the 


reverberation depth is automatically set to 0. 
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When data is left in the reverberation work area, noise will appear when the 


reverberation depth is set. The following procedure can be used to circumvent this 


problem. 
SsUtSetReverbType(SS_REV...); 
SsUtReverbOn(); 
Wait several seconds 


SsUtSetReverbDepth(64,64); 


Number and type are as shown in the table above 


Return Value 





Type is returned if the reverberation type was successfully set, otherwise -1 is returned. 


See Also 





SsUtGetReverbType(), SsUtSetReverbDepth(), SsUtSetReverbFeedback(), 


SsUtSetReverbDelay() 
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SsUtSetVVol 


Syntax 





short SsUtSetVVol ( 
short ve, 
short voll, 


short volr 
) 
Arguments 


ve 
voll 


volr 


Explanation 





Volume (right) 


Sets voice volume 


The volume of the voice specified by vc is set to the values specified by voll (left) and 


volr (right). 


Return Value 





0 is returned if the volume was successfully set, otherwise -1 is returned. 


See Also 





SsUtGetVVol() 
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SsVabClose 


Syntax 





void SsVabClose( 


short vab_id 


) 
Arguments 

vab_id VAB ID 
Explanation 





The VAB data specified by vab_id is closed. 


Return Value 


None 


See Also 





SsVabTransfer() 


Closes VAB data 
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SsVabTransfer 


Accesses and transfers VAB waveform data 


Syntax 





short SsVabTransfer ( 
unsigned char *vh_addr, 
unsigned char *vb_addr, 


short vabid, 


short i_flag 
) 
Arguments 
vh_addr Pointer to start of VH data 
vb_addr Pointer to start of VB data 
vabid VAB ID 
i_flag Must be set to 1 
Explanation 





The sound source header list (VH data) pointed to by vh_addr is accessed and the 
corresponding waveform data (VB data) pointed to by vb_addr is transferred to the 
SPU sound buffer. The VAB identification number is specified in vabid. When vabid is 


-1, SsVabTransfer() allocates and returns an available VAB ID number (0-15). 


Return Value 





The VAB ID number is returned if the VAB data was successfully transferred to the 
SPU sound buffer. If the function fails to complete, one of the following values is 


returned: 
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See Also 





3 
=) 


-3 or greater 


SsVabClose() 


VAB ID cannot be assigned or invalid VH 
Invalid VB 


Other errors 
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abs 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Absolute value 


#include <stdlib.h> 
long abs ( 
long i 


) 


i Integer argument 


The absolute value of i is calculated and its value is returned. 
Since int and long are declared as the same type in the R3000, this function is 


equivalent to labs(). 


The absolute value of i is returned. 


labs() 
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atoi 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Converts a string to an integer 


#include <stdlib.h> 
long atoi ( 
const char *s 


) 


sS Pointer to a character string 


The string pointed to by s is converted to its integer equivalent and its value is 
returned. 
atoi(s) is equivalent to (long)strtol(s,(char**)NULL). Since int and long are declared 


as the same type in the R3000, atoi() is also equivalent to atol(). 


The integer value of the converted character string is returned. 


atol(), strtol() 
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atol 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Converts a string to an integer 


#include <stdlib.h> 
long atol( 


const char *s 


) 


sS Pointer to a character string 


The string pointed to by s is converted to its integer equivalent and its value is 
returned. 
atol(s) is equivalent to (long)strtol(s,(char**)NULL). Since int and long are declared 


as the same type in the R3000, atol() is also equivalent to atoi(). 


The integer value of the converted character string is returned. 


atoi(), strtol() 
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bemp 


Syntax 





Arguments 


Explanation 





Return Value 





Compares two memory blocks 


#include <memory.h> 
long bemp( 

char *b1, 

char *b2, 

long n 


) 


bl Pointer to memory block 1 
b2 Pointer to memory block 2 


n Number of bytes to compare 


The first n bytes of the memory blocks pointed to by b/ and b2 are compared and the 


result is indicated in the return value. 


The result of the comparison is indicated in the return value as shown below. 


| Result | Return Value 
bl<b2 <0 


bl=b2 


b1>b2 
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See Also 





memcemp() 
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bcopy 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Copies memory 


#include <memory.h> 
void beopy( 

char * src, 

char * dest, 

long n 


) 


STC Pointer to source data area 
dest Pointer to destination data area 


n Number of bytes to copy 


The first n bytes of the data area pointed to by src are copied to the data area pointed to 


by dest. 


None 


memcpy() 
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bsearch 
Binary search 

Syntax 

#include <stdlib.h> 

void *bsearch ( 

const void *key, 

const void *base, 

size_t n, 

size_t w, 

long(*fcemp)(const void *, const void *) 

) 
Arguments 

key Pointer to data which is the retrieval key 

base Pointer to destination area to be searched 

n Number of elements in the data area 

w Size of 1 element 

femp Pointer to comparison function 
Explanation 





A binary search for the retrieval key pointed to by key is made in the destination area 
pointed to by base using the comparison function femp. A pointer to the found item is 
returned. 

base is considered to be an array of n items with size w. The search is performed 
looking for the first item that matches the retrieval key. femp must return a value 


representing the result of the comparison as in bemp(). 
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Return Value 





The address of the first item matching the retrieval key is returned. 0 is returned if a 


matching item was not found. 
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bzero 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Clears memory 


#include <memory.h> 
void *bzero ( 


unsigned char *p, 


intn 

} 

p Pointer to a memory block 
n Number of bytes to clear 


The first n bytes of the memory block pointed to by p are cleared. 


p, a pointer to the start of the memory block is returned. 


bcopy(), bemp() 
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calloc 
Allocates memory 
Syntax 
#include <stdlib.h> 
void *calloc ( 
size_tn, 
size_t s 
) 
Arguments 
n Number of blocks to allocate 
sS Block size 
Explanation 





An n xs byte block is allocated from the heap. The allocated memory is cleared. 


Return Value 





A pointer to the allocated memory block is returned. NULL is returned if the allocation 


failed. 


See Also 





malloc(), realloc(), freeQ) 
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free 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Frees allocated memory blocks 


#include <stdlib.h> 
void free ( 

void* block 

) 


block Pointer to allocated memory to be freed 


The memory area pointed to by block and previously allocated by calloc(), malloc() or 


realloc() is freed. 


None 


calloc(), malloc(), realloc() 
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getc 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Gets one character from an input stream 


#include <stdio.h> 
char gete ( 

FILE *stream 

) 


stream Pointer to an input stream 


The next character is read from the input stream pointed to by stream. The character is 


returned by the function. 


The next character read from the input stream is returned if the function was successful. 


Otherwise, EOF is returned in case of end-of-file or error. 


getchar(), gets() 
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getchar 
Gets one character from the standard input stream 

Syntax 

#include <stdio.h> 

char getchar( void ) 
Arguments 

None 
Explanation 





The next character is read from the standard input stream and returned. 


getchar() is equivalent to getc(stdin). 


Return Value 





The next character read from the standard input stream is returned if the function was 


successful. Otherwise, EOF is returned in case of end-of-file or error. 


See Also 





getc(), gets() 
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gets 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Reads a line from the standard input stream 


#include <stdio.h> 
char * gets ( 
char * 5 


) 


Ss Pointer to destination buffer 


A line is read from the standard input stream (stdin) and placed in the buffer pointed to 
by s. The end of line is indicated by a newline character. The newline is discarded and 


replaced by a null character at the end of the string pointed to by s. 


A pointer to the character string s is returned if the function was successful. NULL is 


returned in case of end-of-file or error. 


getc(), getchar() 
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isXXX 
Performs character testing 

Syntax 

#include <ctype.h> 

long isXXX ( 

long c 

) 
Arguments 

c Input character 
Explanation 





isXXX defines a general class of macros. The character c is tested according to one of 
the conditions shown in the following table. The specified macro returns a non-zero 


value if the test succeeded and 0 if the condition was not met. 
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Function Name Condition 


isalnum isalpha(c) || isdigit(c) 
isalpha isupper(c) || islower(c) 
isascii ASCII characters 
iscntrl Control characters 
isdigit Decimal characters 
isgraph Printable characters except spaces 
islower Lower case characters 


isprint Printable characters including spaces 


ispunct Printable characters except spaces, English letters and numbers 


isspace Spaces, page breaks, line feeds, carriage returns, tabs 


isupper Upper case letters 


Hexadecimal characters 





Return Value 





A non-zero value is returned if the input character c satisfied the condition. 0 is 


returned if the condition was not satisfied. 
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labs 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Absolute value 


#include <stdlib.h> 
long labs ( 
long i 


) 


i Integer argument 


The absolute value of i is calculated and its value is returned. 
Since int and long are declared as the same type in the R3000, this function is 


equivalent to abs(). 


The absolute value of i is returned. 


abs() 
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longjmp 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Non-local jump 


#include <setjmp.h> 


void longjmp ( 


jmp_bufp, 

int val 

) 

p Environment storage variable 
val Specified return value of setjmp() 


The program jumps to the location specified in the environment storage area pointed to 


by p which was set by a previous call to setjmp(). 


After a longjmp() is completed, program execution continues as if the corresponding 
invocation of setjmp() had just returned the value specified by val. longjmp() cannot 


cause setjmp() to return the value 0; if va/ is 0, setjmp() returns the value 1. 


setjmp() 
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malloc 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Allocates memory 


#include <stdlib.h> 
void *malloc ( 
size_t s 


) 


sS Number of bytes to allocate 


A block of s bytes is allocated from the heap. 


A pointer to the allocated memory block is returned. NULL is returned if the allocation 
failed. 

* At the time of user program activation heap memory is defined as follows: 

Bottom address Highest address of module + 4 


Top address Highest available memory - 64KB 


calloc(), realloc(), free() 
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memchr 


Syntax 





Arguments 


Explanation 





Return Value 





Searches a memory block for a specified character 


#include <memory.h> 
void *memchr ( 


const void *s, 


long c, 

size_tn 

) 

sS Pointer to a memory block 

c Desired character 

n Maximum number of bytes to search 


The first occurrence of the character c in the memory block pointed to by s is located 
and a pointer to the character is returned. At most n bytes of the memory block will be 


searched. 


A pointer to the located character c is returned. NULL is returned if c cannot be found 


in the memory block. 
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memcmp 


Syntax 





Arguments 


Explanation 





Return Value 
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Compares two memory blocks 


#include <memory.h> 
long memcmp ( 
const void *s/, 


const void *s2, 


size_tn 

) 

sl Pointer to memory block 1 

s2 Pointer to memory block 2 

n Maximum number of bytes to compare 


The first n bytes of the memory blocks pointed to by s/ and s2 are compared and the 


result is indicated in the return value. 


The result of the comparison is indicated in the return value as shown below. 
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See Also 





bemp(Q) 
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memcpy 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Copies a memory block 


#include <memory.h> 
void *memcpy ( 
void *dest, 


const void *src, 


size_tn 

) 

dest Pointer to destination memory block 
STC Pointer to source memory block 

n Number of bytes to copy 


The first n bytes of the memory block pointed to by src are copied to the memory block 


pointed to by dest. 


dest, a pointer to the destination memory block is returned. 


beopy() 
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memmove 
Copies a memory block 

Syntax 

#include <memory.h> 

void *memmove ( 

void *dest, 

const void *src, 

size_tn 

) 
Arguments 

dest Pointer to destination memory block 

STC Pointer to source memory block 

n Number of bytes to copy 


Explanation 


The first n bytes of the memory block pointed to by src are copied to the memory block 
pointed to by dest. 


The block is copied correctly even if src and dest overlap. 


Return Value 





dest, a pointer to the destination memory block is returned. 
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memset 
Writes a specified character to a memory block 
Syntax 
#include <memory.h> 
void *memset ( 
const void *s, 
long c, 
size_tn 
) 
Arguments 
sS Pointer to destination memory block 
c Fill character 
n Number of characters 
Explanation 





The first n bytes of the memory block pointed to by s are filled with the character c. 


Return Value 





s, a pointer to the destination memory block is returned. 
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printf 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Writes formatted output to the standard output stream 


#include <stdio.h> 
long printf ( 
const char *fmt[ argument ...] 


) 


fmt Input format conversion string 


Writes formatted output to stdout, the standard output stream. 
Please refer to the C language reference for a detailed explanation of the input format 


conversion string. The format specifiers “f”, “e”, “E”, “g” and “G” cannot be used. 


printf2() of the mathematical function service is used to display floating-point numbers. 


The length of the output character string is returned. NULL is returned if an error 


occurred. 


sprintf(), printf2() 
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pute 
Writes one character to an output stream 

Syntax 

#include <stdio.h> 

void pute ( 

long c, 

FILE *stream 

) 
Arguments 

c Output character 

stream Pointer to output stream 
Explanation 





The character c is written to the output stream pointed to by stream. 


Return Value 





None 


See Also 





putchar(), puts() 
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putchar 
Writes one character to the standard output stream 

Syntax 

#include <stdio.h> 

long putchar ( 

char c, 

) 
Arguments 

c Output character 
Explanation 





The character c is written to the standard output stream. 


putchar() is equivalent to putc(stdout). 
Return Value 
None 


See Also 





putc(), puts() 
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puts 
Writes a character string to the standard output stream 

Syntax 

#include <stdio.h> 

void puts ( 

const char *s 

) 
Arguments 

sS Output character string 
Explanation 





The character string s is written to the standard output stream (stdout). A newline 


character is appended to the end of the string. 


Return Value 


None 


See Also 





putc(), putchar() 
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qsort 


Syntax 





Arguments 


Explanation 


Quick sort 


#include <stdlib.h> 
void qsort ( 

void *base, 
size_tn, 

size_t w, 


long (¥fcmp)(const void *, const void *) 


) 

base Pointer to array in memory to be sorted 
n Number of elements 

w Size of each element 

femp Pointer to comparison function 


The array pointed to by base is sorted using a quicksort algorithm. 

n specifies the number of elements in the array and w is the size of each element. 

femp is the comparison function and must return a value representing the result of the 
comparison as in bemp(). 

qsort() calls malloc() internally so there must be sufficient space on the heap to perform 


the sort. 
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Return Value 





None 
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rand 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Generates a random number 


#include <stdlib.h> 


long rand ( void ) 


None 


A pseudo-random number is generated between 0 and RAND_MAX(0x7FFF=32767) 


and its value is returned. 


The generated pseudo random number is returned. 


srand() 
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realloc 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Reallocates memory 


#include <stdlib.h> 


void *realloc ( 


void *block, 

size_t s 

) 

block Pointer to area to be reallocated 
Ss Size of new area 


The previously allocated area of storage pointed to by block is reallocated to the size 


specified by s. realloc() is identical to malloc() if block is NULL. 


A pointer to the reallocated block is returned. The reallocated block may be located at a 
different address than the original block. NULL is returned if the allocation failed in 


which case the original block is not released. 


calloc(), malloc(), free() 
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setjmp 
Defines destination of longjmp() 

Syntax 

#include <setjmp.h> 

int setjmp ( 

jmp_buf p 

) 
Arguments 

Pp Environment storage variable 
Explanation 





Saves environmental information (such as the stack pointer) in the memory area pointed 


to by p for later use by longjmp(). 


Return Value 





When setjmp() is directly invoked, 0 is returned. If the return is from a call to 


longjmp(), val, the argument to longjmp() is returned. 


See Also 





longjmp() 
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sprintf 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Writes formatted output to a character string 


#include <stdio.h> 
long sprintf( 
char *s, 


const char *fm¢[,argument...] 


) 
sS Pointer to storage area holding converted character string 
fmt Input format conversion string 


Writes formatted output to a character string and places the result in the storage area 
pointed to by s. 

Please refer to the C language reference for a detailed explanation of the input format 

conversion string. The format specifiers “f”, “e”, “E”, “g” and “G” cannot be used. 


sprintf2() of the mathematical function service is used to display floating-point 


numbers. 


The length of the output character string is returned. NULL is returned if an error 


occurred. 


printfQ, sprintf2() 
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srand 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Initializes the random number generator 


#include <stdlib.h> 
void srand ( 


unsigned int seed 


) 


seed Random number seed 


Sets the new seed for the random number generator to the value specified by seed. The 
random number generator is reinitialized to its initial starting point by specifying a 


seed of 1. 


None 


rand() 
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strcat 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 
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Concatenates two character strings 


#include <strings.h> 
char *streat ( 
char * dest, 


const char *src 


) 
dest Pointer to destination character string 
src Pointer to source character string 


The string pointed to by src is concatenated to the end of the string pointed to by dest. 


A pointer to the concatenated string is returned. 


dest, a pointer to the concatenated string is returned. 


strncat() 
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strchr 


Syntax 





Arguments 


Explanation 





Return Value 





Searches for the first occurrence of a specified character in a 
character string 


#include <strings.h> 
char *strchr ( 


const char *s, 


long c 

) 

sS Pointer to a character string 
c Target character 


The first occurrence of the character c is located in the string pointed to by s. A pointer 


to the located character is returned. 


A pointer to the first occurrence of the character c within the string s is returned. 


NULL is returned if c cannot be found within s. 


249 


EEE Standard C Library 





strcmp 


Syntax 





Arguments 


Explanation 





Return Value 
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Compares two character strings 


#include <strings.h> 
long stremp ( 
const char *s/, 


const char *s2 


) 
sl Pointer to string 1 
s2 Pointer to string 2 


The string pointed to by s/ is compared with the string pointed to by s2, character-by- 


character as unsigned chars, and the result is indicated in the return value. 


The result of the comparison is indicated in the return value as shown below. 





Co o 
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strcpy 


Syntax 





Arguments 


Explanation 





Return Value 





See Also 





Copies a character string 


#include <strings.h> 
char *strepy ( 
char *dest, 


const char *src 


dest Pointer to destination memory area 
src Pointer to source character string 


The string pointed to by src is copied to the memory area pointed to by dest. 


dest, a pointer to the destination string is returned. 


strncpy() 
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strcspn 


Syntax 


Arguments 





Explanation 


Return Value 
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Searches for a character string comprising only characters not 
included in a specified character set 


#include <strings.h> 
size_t strespn ( 
const char *s/, 


const char *s2 


) 
sl Pointer to target character string to be searched 
s2 Pointer to string which contains the character set 


The character string starting from the beginning of the string pointed to by s/ that does 
not contain any characters that are contained in the character set pointed to by s2 is 


located and its length is returned. 


The length of the segment within the string pointed to by s/ that does not contain any 


characters from the string pointed to by s2 is returned. 
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strlen 


Syntax 





Arguments 


Explanation 





Return Value 





Finds the length of a character string 


#include <strings.h> 
long strlen ( 


const char *s 


) 


sS Pointer to a character string 


The length of the string pointed to by s (i.e. the number of characters in the string) is 


obtained and its value is returned. 


The length of the string pointed to by s is returned. 
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strncat 
Concatenates two character strings 

Syntax 

#include <strings.h> 

char *strncat ( 

char * dest, 

const char *src, 

size_tn 

) 
Arguments 

dest Pointer to destination character string 

STC Pointer to source character string 

n Number of characters from source string to concatenate 
Explanation 





n characters from the string pointed to by src are concatenated to the end of the string 


pointed to by dest. The concatenated string is returned. 


Return Value 





dest, a pointer to the concatenated string is returned. 
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strncmp 


Syntax 





Arguments 


Explanation 





Return Value 





Compares two character strings 


#include <strings.h> 
long stnemp ( 
const char *s/, 


const char *s2, 


size_tn 

) 

sl Pointer to string 1 

s2 Pointer to string 2 

n Number of characters to compare 


The first n characters of the string pointed to by s/ are compared to the corresponding 
characters of the string pointed to by s2, character-by-character as unsigned chars, and 


the result is indicated in the return value. 


The result of the comparison is indicated in the return value as shown below. 
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strncepy 


Syntax 





Arguments 


Explanation 





Return Value 
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#include <strings.h> 


char *strnepy ( 
char * dest, 
const char *src, 
size_tn 


) 


dest 


STC 


Copies a character string 


Pointer to destination memory area 
Pointer to source character string 


Number of bytes to copy 


n bytes of the string pointed to by src are copied to the memory area pointed to by dest. 


dest, a pointer to the destination string is returned. 
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strpbrk 


Syntax 


Arguments 





Explanation 


Return Value 





Searches for the first occurrence of a specified character in a 
character set 


#include <strings.h> 
char *strpbrk ( 
const char *s/, 


const char *s2 


) 
sl Pointer to string to be searched 
s2 Pointer to string containing the character set 


The character string pointed to by s/ is searched for the first occurrence of any character 
contained in the string pointed to by s2. A pointer to the character within s2 is 


returned. 


A pointer to the character within s2 is returned. NULL is returned if none of the 


characters in the string pointed to by s2 are contained within the character set. 
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strrchr 


Syntax 





Arguments 


Explanation 





Return Value 
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Searches for the last occurrence of a specified character in a 
character string 


#include <strings.h> 
char *strrehr ( 


const char *s, 


long c 

) 

sS Pointer to a character string 
c Target character 


The last occurrence of the character c is located in the character string pointed to by s. 


A pointer to the located character is returned. 


A pointer to the last occurrence of the character c within the string pointed to by s is 


returned. NULL is returned if c cannot be found within the string. 
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strspn 
Searches for a character string comprising only characters in a 
specified character set 
Syntax 
#include <strings.h> 
size_t strspn ( 
const char *s/, 
const char *s2 
) 
Arguments 
sl Pointer to target character string to be searched 
s2 Pointer to string containing the character set 
Explanation 





The character string starting from the beginning of the string pointed to by s/ that 
contains only characters from the string pointed to by s2 is located and its length is 


returned. 


Return Value 





The length of the segment within the string pointed to by s/ that contains only 


characters from the string pointed to by s2 is returned. 
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strstr 


Syntax 





Arguments 


Explanation 





Return Value 
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Searches for the occurrence of a specified partial character 
string 


#include <strings.h> 
char * strstr ( 
const char *s/, 


const char *s2 


) 
sl Pointer to target character string to be searched 
s2 Pointer to character string to be located 


The first occurrence of the string pointed to by s2 is located within the string pointed 


to by s1. A pointer to the position of s2 within the string pointed to by s/ is returned. 


A pointer to the position of the located string pointed to by s2 within the string 
pointed to by s/ is returned. NULL is returned if the string pointed to by s2 is not 


contained within the string pointed to by s1. 





strtok 


Syntax 





Arguments 


Explanation 
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Searches for a character string bounded by characters in a 
specified set of delimiters 


#include <strings.h> 
char *strtok ( 
char *s/, 


const char *s2 


) 
sl Pointer to target character string to search 
s2 Pointer to character set containing token delimiters 


A sequence of calls to strtok() breaks the string pointed to by s/ into a sequence of 
tokens, each of which is delimited by a character from the string pointed to by s2. The 
first call in the sequence has s/ as its first argument, and is followed by calls with a 
NULL pointer as their first argument. 

The first call in the sequence searches the string pointed to by s/ for the first character 
that is not contained in the current separator string pointed to by s2. Ifno such 
character is found, then there are no tokens in the string pointed to by s/ and the 
function returns a NULL pointer. If such a character is found, it is the start of the first 


token. 
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strtok() then searches from there for a character that is contained in the current separator 
string. If no such character is found, the current token extends to the end of the string 
pointed to by s/, and subsequent searches for a token will return a NULL pointer. If 
such a character is found, it is overwritten by a NULL character, which terminates the 
current token. strtok() saves a pointer to the following character, from which the next 
search for a token will start. 

Each subsequent call, with a NULL pointer as the value of the first argument, starts 


searching from the saved pointer and behaves as described above. 


Return Value 





A pointer to the first character of a token is returned, or NULL is returned if there is no 


token. 
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strtol 


Syntax 





Arguments 


Explanation 





Converts a character string to an integer 


#include <stdlib.h> 
long strtol ( 
const char *s, 


char **endp 


) 
sS Pointer to a character string 
endp Pointer to a storage area that will contain a pointer to the 


character that stopped the conversion 


The character string pointed to by s is converted to an integer and its value is returned. 
Note that long and int are declared as the same type in the R3000. 


The string pointed to by s must be in one of the following formats. 


[ws][sn][ddd] 

[ws] White space (can be omitted) 
[sn] Sign (can be omitted) 

[ddd] Number string (can be omitted) 


strtol() stops conversion when a character is encountered that cannot be converted. 
endp A pointer to the character that terminated the conversion is placed at the storage 


location specified by endp unless endp is NULL. 
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Return Value 





The result of converting the character string pointed to by s to an integer is returned if 


the conversion was successful. 0 is returned if an error occurred. 


See Also 





strtoul() 
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strtoul 


Syntax 





Arguments 


Explanation 





Converts a character string to an unsigned integer 


#include <stdlib.h> 
unsigned long strtoul ( 
const char *s, 


char **endp 


) 
sS Pointer to a character string 
endp Pointer to a storage area that will contain a pointer to the 


character that stopped the conversion 


The character string pointed to by s is converted to an unsigned integer and its value 
is returned. Note that long and int are declared as the same type in the R3000. 


The string pointed to by s must be in one of the following formats. 


[ws][sn][ddd] 

[ws] White space (can be omitted) 
[sn] Sign (can be omitted) 

[ddd] Number string (can be omitted) 


strtol() stops conversion when a character is encountered that cannot be converted. A 
pointer to the character that terminated the conversion is placed at the storage location 


specified by endp unless endp is NULL. 
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Return Value 





The result of converting the character string pointed to by s to an unsigned integer is 


returned if the conversion was successful. 0 is returned if an error occurred. 


See Also 





strtol() 
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toascii 
Masks off bit 7 of a specified character 

Syntax 

#include <ctype.h> 

long toascii ( 

long c 

) 
Arguments 

c Input character 
Explanation 





Bit 7 of the input character c is masked off. 


Return Value 


The result of the masking operation is returned. 
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tolower 
Converts a character to lower case 

Syntax 

#include <ctype.h> 

long tolower ( 

long c 

) 
Arguments 

c Input character 
Explanation 





The input character c is converted to lower case. 


Return Value 





The lower case character corresponding to the input character c is returned. 
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toupper 


Syntax 





Arguments 


Explanation 





Return Value 





Converts a character to upper case 


#include <ctype.h> 
long toupper ( 
long c 


) 


c Input character 


The input character c is converted to upper case. 


The upper case character corresponding to the input character c is returned. 
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acos 
Arccosine 

Structure 

double acos ( 

double x 

) 
Arguments 

x Argument. Range is [-1 to 1]. 
Explanation 





The arccosine of x is calculated and its value is returned. 


Return value 





The arccosine of x (acos(x)) is returned. The result range is [0, pi]. 


Error processing is shown in the table below. 


[cenaon[ Ratwnvane [ever | 





See Also 





cos(), asin(), atan() 
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asin 


Structure 





Arguments 


Explanation 





Return value 





See Also 





Arcsine 


double asin ( 


double x 


) 
x Argument. Range is [-1 to 1]. 
The arcsine of x is calculated and its value is returned. 


The arcsine of x (asin(x)) is returned. The result range is [-pi/2, pi/2]. 


Error processing is shown in the table below. 


[“cenaion | reuma [ver] 





sin(), acos(), atan() 
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atan 
Arctangent 

Structure 

double atan ( 

double x 

) 
Arguments 

x Argument. 
Explanation 





The arctangent of x is calculated and its value is returned. 


Return value 





The arctangent of x (atan(x)) is returned. The result range is [-pi/2, pi/2]. 


See Also 





tan(), asin(), acos(), atan2() 
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atan2 
Arctangent 

Structure 

double atan2 ( 

double x, 

double y 

) 
Arguments 

x Dividend 

y Divisor 
Explanation 





The arctangent of x/y is calculated and its value is returned. 


Return value 





The arctangent of x/y (atan(x/v)) is returned. The result range is [-pi, pi]. 


Error processing is shown in the table below. 


C erann [| Rewmvane [ever | 





See Also 





atan() 
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atof 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 
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Converts a character string to a floating-point number 


double atof( 


const char *s 


) 


sS Pointer to a character string 


The character string pointed to by s which represents a floating point number, is 


converted to a double-precision floating point value. 


The result of converting the input string pointed to by s to a double-precision value is 
returned. If the value exceeds the range that can be expressed, either 
+HUGE_VAL(1.797693134862316e+308) or -HUGE_VAL is returned according to 


the sign. 0 is returned if an underflow occurs. 


Error processing is shown in the following table. 


Domain error 





Outside the range that +/- HUGE_VAL Domain error 
can be expressed 
oe o 
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See Also 


strtod() 
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ceil 
Finds the smallest integer not less than x (ceiling function) 

Structure 

double ceil ( 

double x 

) 
Arguments 

x Argument 
Explanation 





The smallest integer greater than or equal to x is obtained and its corresponding 


double-precision floating point value is returned. 


Return value 





The smallest integer (in double-precision floating point format) that is not less than x 


is returned. 


See Also 





floor() 
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cos 
Cosine 

Structure 

double cos ( 

double x 

) 
Arguments 

x Argument in radians 
Explanation 





The cosine of x is calculated and its value is returned. 


Return value 





The cosine of x (cos(x)) is returned. 


See Also 





sin(), tan(), acos() 
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cosh 
Hyperbolic cosine 

Structure 

double cosh ( 

double x 

) 
Arguments 

x Argument in radians 
Explanation 





The hyperbolic cosine of x is calculated and its value is returned. 


Return value 





The hyperbolic cosine of x (cosh(x)) is returned. 


See Also 





sinh(), tanh() 
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exp 
Exponent 

Syntax 

double exp ( 

double x 

) 
Arguments 

x Argument 
Explanation 





The exponential of x (e to the x-th power) is calculated and the result is returned. 


Return Value 





e to the x-th power (e’) is returned. 


See Also 





pow(), log() 
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fabs 
Absolute value (macro) 

Syntax 

fabs ( 

double x 

) 
Arguments 

x Floating-point argument 
Explanation 





The absolute value of the argument x is calculated and its value is returned. 


Return Value 





The absolute value of x is returned. 


Notes 





fabs() is a macro. 
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floor 


Structure 





Arguments 


Explanation 





Return value 





See Also 





Finds the largest integer not greater than x (base function) 


double floor ( 


double x 


) 


x Argument 


The largest integer less than or equal to x is obtained and its corresponding double- 


precision floating point value is returned. 


The largest integer (in double-precision floating point format) that is not greater than x 


is returned. 


ceil() 
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fmod 
Calculates floating point remainder of x/y 

Structure 

double fmod ( 

double x, 

double y 

) 
Arguments 

x Floating point dividend 

y Floating point divisor 
Explanation 





The remainder of x/y is calculated and its value is returned as a double-precision 


floating point number. 


Return value 





The double precision floating point number remainder of x/y is returned. 


Notes 





The sign of the return value will be the same as the sign of x. 0 is returned if y is 0. 
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frexp 


Structure 





Arguments 


Explanation 


Return value 





Notes 





Divides a floating point number into a normalized mantissa 
and an exponent ( ) 


double frexp ( 


double x, 

int *n 

) 

x Argument 

n Pointer to a storage location that stores the exponent 


The floating point number x is separated into a normalized mantissa [1/2,1) and an 
exponent( ). The exponent is placed at the storage location pointed to by n. 


The normalized mantissa is returned by the function. 


The normalized mantissa [1/2, 1) is returned. 


[ a,b) indicates a value in the range: a < value < b. 
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hypot 
Absolute value of a complex number 

Structure 

double hypot ( 

double x, 

double y 

) 
Arguments 

x Real part 

y Imaginary part 
Explanation 





The absolute value of the complex number (x+iy) is calculated and its value is returned. 


Return value 





The square root of the sum of x and y’ is returned. 
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Idexp 
Calculates a real number from a mantissa and an exponent 

Structure 

double Idexp ( 

double x, 

long n 

) 
Arguments 

x Floating point mantissa 

n Integer exponent 
Explanation 





The real number is calculated and its value is returned. 


Return value 


The value x x 2” is returned. 
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log 
Natural logarithm 

Syntax 

double log ( 

double x 

) 
Arguments 

x Argument 
Explanation 





The natural logarithm of x is calculated and the result is returned. 


Return Value 





The natural logarithm of x ( In(x) ) is returned. 


Notes 





x must be greater than 0, otherwise an error will occur as shown below. 





See Also 





exp(), log10Q) 
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log10 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





See Also 





Common logarithm 


double log10 ( 
double x 


) 


x Argument 


The common logarithm of x is calculated and the result is returned. 


The common logarithm of x ( log10(x) ) is returned. 


x must be greater than 0, otherwise an error will occur as shown below. 





log) 
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modf 


Structure 





Arguments 


Explanation 





Return value 





Notes 
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Separates a floating point number into integer and fractional 
parts 


double modf ( 
double x, 
double *y 

) 


x Floating point number 


y Pointer to a buffer for storing the integer part 


x is separated into an integer part and a fractional part. The integer part is placed at the 


storage location pointed to by y. The fractional part is returned by the function. 


The fractional part of x is returned. 


The sign for both integer parts and fractional parts will be the same as the sign of x. 
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pow 


Syntax 





Arguments 


Explanation 





Return Value 





Notes 





x to the y-th power 


double pow ( 


double x, 

double y 

) 

x Base number 
y Power 


x to the y-th power is calculated and the result is returned. 


x to the y-th power (x’) is returned. 


Error processing is shown in the following table. 


o ome oe ooo 
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See Also 





exp() 
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printf2 


Writes formatted output to the standard output stream (supports float and 
double type) 





Structure 

long printf2( 

const char *fmt, [argument...] 

) 
Arguments 

fmt Input format conversion string 
Explanation 





Writes formatted output to stdout, the standard output stream. 
Please refer to the C language reference for a detailed explanation of the input format 


conversion string. The format specifiers “f’, “e”, “E”, “g” and “G” can be used. 


printf2() requires more stack space than print(). 


Return Value 





The length of the output character string is returned. NULL is returned if an error 


occurred. 


See Also 





sprintf2() 
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sin 


Structure 





Arguments 


Explanation 





Return value 





See Also 
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double sin ( 


double x 


) 


x Argument in radians 


The sine of x is calculated and its value is returned. 


The sine of x (sin(x)) is returned. 


cos(), tan(), asin() 


Sine 
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sinh 
Hyperbolic sine 

Structure 

double sinh ( 

double x 

) 
Arguments 

x Argument in radians 
Explanation 





The hyperbolic sine of x is calculated and its value is returned. 


Return value 





The hyperbolic sine of x (sinh(x)) is returned. 


See Also 





cosh(), tanh() 
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sprintf2 


Structure 





Arguments 


Explanation 





Return Value 





See Also 
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Writes formatted output to a character string (Supports float and 
double type) 


long sprintf2( 
char *s, 


const char *fmt, [argument...] 


) 
sS Pointer to storage area holding converted character string 
fmt Input format conversion string 


Writes formatted output to a character string and places the result in the storage area 
pointed to by s. 
Please refer to the C language reference for a detailed explanation of the input format 


conversion string. The format specifiers “f’, “e”, “E”, “g” and “G” can be used. 


sprintf2() requires more stack space than sprintf(). 


The length of the output character string is returned. NULL is returned if an error 


occurred. 


printf2() 
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sqrt 


Structure 





Arguments 


Explanation 





Return value 





Square root 


double sqrt ( 


double x 


) 


x Argument (must be = 0) 


The square root of x is calculated and its value is returned. 


The square root of x (sqrt(x)) is returned. 


Error processing is shown in the table below. 
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strtod 


Syntax 





Arguments 


Explanation 
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Converts a character string to a floating-point number 


double strtod( 
const char *s, 


char **endp 


) 
sS Pointer to a character string 
endp Pointer to a storage area that will contain a pointer to the 


character that stopped the conversion 


The character string pointed to by s is converted to a double-precision floating point 
number and its value is returned. 


The string pointed to by s must be in one of the following formats. 


[ws][sn][ddd] 

[ws] White space (can be omitted) 
[sn] Sign (can be omitted) 

[ddd] Number string (can be omitted) 


strtod() stops conversion when a character is encountered that cannot be converted. A 
pointer to the character that terminated the conversion is placed at the storage location 


specified by endp unless endp is NULL. 
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Return Value 





The result of converting the input string pointed to by s to a double-precision value is 
returned. If the value exceeds the range that can be expressed, either 
+HUGE_VAL(1.797693134862316e+308) or -HUGE_VAL is returned according to 


the sign. 0 is returned if an underflow occurs. 


Notes 





Error processing is shown in the following table. 


Condition Return Value Error 


Outside the range that +/- HUGE_VAL Domain error 
can be expressed 
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tan 


Structure 





Arguments 


Explanation 





Return value 





See Also 
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Tangent 


double tan ( 


double x 


) 


x Argument in radians 


The tangent of x is calculated and its value is returned. 


The tangent of x (tan(x)) is returned. 


sin(), cos(), atan() 
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tanh 
Hyperbolic tangent 

Structure 

double tanh ( 

double x 

) 
Arguments 

x Argument in radians 
Explanation 





The hyperbolic tangent of x is calculated and its value is returned. 


Return value 





The hyperbolic tangent of x (tanh(x)) is returned. 


See Also 





sinh(), cosh() 
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CdIFILE 
ISO-9660 file descriptor 
Structure 
typedef struct { 
CdlLOC pos; 
u_long size; 
char name[16]; 
} CdlFILE; 
Members 
pos File position 
size File size 
name Filename 
Explanation 





CdIFILE holds information that describes a file on the CD-ROM in the ISO-9660 file 


system. 
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CdILOC 


Structure 





Members 





Explanation 





Notes 





typedef struct { 


} CdILOC; 


minute 
second 
sector 


track 


CD-ROM location 


u_char minute; 
u_char second; 
u_char sector; 


u_char track; 


Minute 
Second 
Sector 


Track number 


CDILOC holds information that describes a physical location on the CD-ROM. 


The track member is not currently supported. 
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CdPlay 
Plays back CD-DA tracks 

Structure 

int CdPlay ( 

int mode, 

int *tracks, 

int offset 

) 
Arguments 

mode Mode (see below) 

tracks Pointer to array that specifies the track to be played. The last 

element must be 0. 

offset Index into the tracks array where playback will begin 

Explanation 





The sequence of track numbers starting at the array element specified by tracks/offset] 
is played one after another. When the end of the sequence is reached, playback is 


repeated or ended according to the setting of mode as shown in the table below. 
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Notes 
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Description 
Stop playback immediately. 


The tracks specified by tracks are played consecutively, and playback is stopped 
when all the specified tracks have been played. 


The tracks specified by tracks are played consecutively, and playback is returned to 
the start and repeated when all the specified tracks have been played. 


The index of the tracks array for the track currently being played is returned. (No 
other action is taken.) 





The array index of the track currently being played is returned (not the track number 


itself). -1 is returned on error or if there is no song playing. 


All playback is in units of tracks. Therefore, it is not possible to start or stop or 


playing in the middle of a track. 
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CdReadExec 


Loads executable files from the CD-ROM 


Structure 





struct EXEC *CdReadExec( 


char *file 

) 
Arguments 

file Executable filename 
Explanation 





The executable file specified by file is read from the CD-ROM and placed at the memory 
location specified in the header of the executable file. 

Reading is performed in the background, so CdReadSync() should be used to determine 
when reading has completed. 


The loaded file can be executed as a child process using Exec(). 


Return value 





A pointer to the EXEC structure containing information about the executable files that 


has been loaded is returned. 


Notes 





The load address of the executable file should not overlap the area used by the parent 


process. 
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CdReadFile 
Reads a data file from the CD-ROM 

Structure 

int CdReadFile( 

char *file, 

u_long *addr, 

int nbyte 

) 
Arguments 

file Filename 

addr Pointer to result memory buffer 

nbyte Number of bytes to read 
Explanation 





nbyte bytes of the file specified by file are read from the CD-ROM and placed in the 
buffer pointed to by addr. 
Ifnbyte is set to 0, the entire file is read. If file is set to NULL, the function starts 


reading at the last location read by the previous call. 


Return value 





The number of bytes read is returned if the function was successful. 0 is returned in case 


of an error. 
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Notes 





The filename must be specified as an absolute path with lower case characters 


automatically converted to upper case. 


Reading is performed in the background, so CdReadSync() should be used to determine 


when reading has completed. 
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CdReadSync 


Structure 





Arguments 


Explanation 





Return value 





Waits for completion of CdRead 


int CdReadSync ( 
int mode, 


u_char *result 


) 
mode 0: Wait for completion of read 

1: Obtain current status and return immediately 
result Pointer to buffer storing the result 


CdReadSync() waits for reading to complete that was started by CdReadFile() and 
CdReadExec(). 


The return value has the following meaning. 


Positive integer Number of sectors left to 
read 


Read completed 
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CdSearchFile 


Gets location and size of a CD-ROM file 


Structure 





CdlFILE *CdSearchFile ( 
CdlFILE *fp, 


char *name 
) 
Arguments 
Jp Pointer to CD-ROM file structure for storing the result 
name Filename 
Explanation 





The location of the file on the CD-ROM specified by name is obtained (in minutes, 


seconds, sectors) and the result is stored in the CD-ROM file structure pointed to by 


fb. 


Return value 





If the file was found on the CD-ROM, fp, the pointer to the CD-ROM file structure is 


returned. 0 is returned if the file was not found. -1 is returned if an error occurred. 


Notes 





The filename must be specified as an absolute path. 
When the same directory is accessed repeatedly, the file location information is cached 


to improve performance. 
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close 
Closes a file 

Structure 

int close ( 

int fd 

) 
Arguments 

fd File descriptor 
Explanation 





The file specified by the file descriptor, fd, is closed. 


Return value 





fd is returned if the file was successfully closed. -1 is returned in all other cases. 


See Also 





open() 
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delete 


Structure 





Arguments 


Explanation 





Return value 
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Deletes a file 


int delete ( 


char *name 


) 


name Filename 


The file specified by name is deleted. 


1 is returned if the file was successfully deleted. 0 is returned in all other cases. 
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DIRENTRY 


Structure 





Members 





Explanation 





See Also 





struct DIRENTRY { 


name 
attr 
size 
next 
head 


system 


Structure of a directory entry 


char name[20]; 

long attr; 

long size; 

struct DIRENTRY *next 
long head; 


char system[8]; 


Filename 

Attribute (depends on file system) 
File size (bytes) 

Pointer to next file entry (for user) 
Starting sector number 


System reserved 


DIRENTRY stores information relating to files contained in the file system. 


firstfileQ, nextfile() 
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EnterCriticalSection and ExitCriticalSection 


Inhibit and permit interrupts 





Structure 
void EnterCriticalSection(void) 
void ExitCriticalSection(void) 
Arguments 
None 
Explanation 





EnterCriticalSection() inhibits interrupts while in a critical section. 


ExitCriticalSection() enables interrupts after leaving a critical section. 


Return value 





None 
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EXEC 
Structure of an executable file 
Structure 
struct EXEC { 
unsigned long pc0; 
unsigned long gp0; 
unsigned long ¢_addr; 
unsigned long ¢_size; 
unsigned long d_addr; 
unsigned long d_size; 
unsigned long s_addr; 
unsigned long s_size; 
unsigned long sp, fp, gp, base; 
E 
Members 
pco Execution start address 
gp0 gp register initial value 
t_addr Starting address of text section and initialized data 
section 
t_size Size of text section and initialized data section 
d_addr System reserved 
d_size System reserved 
b_addr Starting address of uninitialized data section 
b_size Size of uninitialized data section 
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s_addr Stack start address (user-specified) 
S_ size Stack size (user-specified) 
sp fp gp base Register storage area 


Explanation 


The EXEC structure is located in the upper 2K bytes of an executable file (a file in PS-X 
EXE format). EXEC maintains information used to load and execute a program. 
When a program is executed, stack information is added to the members of the EXEC 


structure and the structure is passed as an argument to the Exec() function. 


See Also 





Exec() 
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Exec 


Structure 





Arguments 


Explanation 





Execute an executable file 


long Exec ( 


struct EXEC *exec, 


long argc, 

char *argv 

) 

exec Pointer to executable file descriptor 
argc Number of arguments 

argv Argument string 


An executable file that has been loaded into memory and which is described by the 


information contained in the EXEC structure pointed to by exec is executed. argc and 


argv are passed to the executable program. 


Ifexec->s_addr is 0, neither the stack pointer nor the frame pointer is initialized. 


The operation of Exec() is shown below. 


() 
(2) 
(3) 
(4) 
(5) 


The uninitialized data section is cleared. 

sp, fp and gp are saved, then initialized (fp is set to the value of sp). 
The arguments of main() are set in the a0 and al registers. 

A jump is made to the execution start address. 


sp, fp and gp are restored after returning. 
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Return value 





1 is returned if the function was successful. 0 is returned in all other cases. 


Notes 





Exec() must be executed in a critical section. 


See Also 





EXEC structure, Load() 
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firstfile 


Structure 





Arguments 


Explanation 





Return value 





Notes 





See Also 





Retrieves information about a file 


struct DIRENTRY “*firstfile ( 
char *name, 


struct DIRENTRY *dir 


) 

name Filename 

dir Pointer to DIRENTRY structure that stores information 
relating 


to the referenced file 


Information about the file corresponding to the specified filename is obtained and 


placed in the DIRENTRY structure pointed to by dir. 


dir is returned if the function is successful. 0 is returned in all other cases. 


The wildcard character ‘*’ can be used in the filename. Characters after the ‘*’ are 


ignored. 


DIRENTRY structure, nextfile() 
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FlushCache 


Flush the I-cache 


Structure 





void FlushCache ( void ) 


Arguments 


None 


Explanation 





The Instruction cache is flushed. 


FlushCache() is usually called when a program modifies instruction code. 


Return value 





None 


Notes 





The contents of the instruction cache cannot be modified. 
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format 
Initializes the file system 

Structure 

int format ( 

char *fs 

) 
Arguments 

fs File system name 
Explanation 





The file system specified by fs is initialized. 


Return value 





1 is returned if the initialization was successful. 0 is returned in all other cases. 


Notes 





format() is valid only for writeable file systems. 
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GetPadBuf 
Gets controller buffers 
Structure 
void GetPadBuf ( 
volatile unsigned char **buf7, 
volatile unsigned char **buf2 
) 
Arguments 
bufl Pointer to a storage location that will contain a pointer to the 
port! controller. 
buf2 Pointer to a storage location that will contain a pointer to the 
port2 controller. 
Explanation 





The storage locations of the system controller buffers are obtained and stored at the 
memory locations pointed to by buf? and buf2. 

Communication with the controllers occurs every vertical synchronization 
interruption and information read from the controllers is stored in the system controller 
buffers. GetPadBuf() can be used to obtain pointers to these buffers. 

There is a separate buffer for each controller. The table below shows the arrangement of 


data within each buffer. 
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Oxff: No controller 
0x00: Controller present 
Upper 4 bits: Terminal type 


Lower 4 bits: Received data size (in 1/2 bytes) 


Received data (maximum 32 bytes) 





The received data format varies according to the type of controller indicated by 
‘terminal type’. The terminal types supported by the library are shown in the 


following table. 





Please refer to the "User’s Guide" for a description of the contents of received data 


corresponding to each terminal type. 


Return value 





None 
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GetRCnt 


Structure 





Arguments 


Explanation 





Return value 





See Also 
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Gets the value of a root counter 


long GetRCnt ( 
unsigned long spec 


) 


spec The specified root counter 


The current value of the root counter specified by spec is returned. 


If the function is successful, the 32-bit unsigned and expanded root counter value is 


returned. -1 is returned if the function failed to complete. 


StartRCnt(), ResetRCnt() 
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GetVideoMode() 


Obtains the currently active video signal mode 


Structure 





long GetVideoMode (void) 


Arguments 
None 


Explanation 





The currently active video signal mode is returned. 


Return value 





The currently active video signal mode is returned and can assume one of the following 





values. 
MODE NTSC: NTSC video signal mode 
MODE PAL: PAL video signal mode 
Notes 
The default mode before SetVideoMode () is called is MODE_NTSC regardless of 
machine type. 
See Also 





SetVideoMode() 
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InitHeap 
Initialize the heap 

Structure 

void InitHeap ( 

void *head, 

long size 

) 
Arguments 

head Pointer to heap start address 

size Heap size (multiple of 4 bytes) 
Explanation 





The heap pointed to by head is initialized. Memory management functions are also 
initialized, so that malloc() and the other memory allocation functions can be used. 


The effective heap size is actually less than size because of overhead. 


Return value 








None 

Notes 
Multiple calls to InitHeap() are permitted only if they do not overlap, otherwise 
memory management functions will not operate properly. 

See Also 





malloc() 
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Load -n 


Structure 





Arguments 


Explanation 





Return value 





See Also 





Loads an executable file 


long Load ( 
char *name, 


struct EXEC *exec 


) 
name Filename 
exec Pointer to an executable file structure for storing the result 


The executable file specified by name is loaded into memory at the address specified in 
its header. Internal information about the file is written to the EXEC structure pointed 


to by exec. 


1 is returned if the function was successful. 0 is returned in all other cases. 


EXEC structure, Exec() 
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LoadTest 


Structure 





Arguments 


Explanation 





Return value 





See Also 
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Test load of an executable file 


long LoadTest ( 
char *name, 


struct EXEC *exec 


) 
name Filename 
exec Pointer to an executable file structure for storing the result 


The information contained in the executable file specified by name is written to the 


structure pointed to by exec. 


The execution start address is returned if the function is successful. 0 is returned in all 


other cases. 


EXEC structure, Load() 
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Iseek 
Moves the file pointer 

Structure 

int lseek ( 

int fd, 

unsigned int offset, 

int flag 

) 
Arguments 

fd File descriptor 

offset Offset 

flag See below 
Explanation 





The file pointer of the device corresponding to the file descriptor specified by fd is 
moved according to the values of offset and flag. 
offset specifies the number of bytes to move the pointer. flag has the meaning indicated 


below. 


SEEK SET Seek from the beginning 
of file. offset is relative to 
the beginning of the file. 


SEEK CUR Seek from the current 
location. offset is relative 
from the current position 
of the file pointer. 
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Iseek() cannot be used with character-type drivers. 


Return value 





The current file pointer is returned if the function succeeded. -1 is returned in all other 


cases. 


See Also 





open(), read(), write() 
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nextfile 


Structure 





Arguments 


Explanation 





Return value 





Notes 





See Also 





Retrieves information about the next file 


struct DIRENTRY *nextfile ( 


struct DIRENTRY *dir 
) 


dir Pointer to DIRENTRY structure that stores information 


relating to the referenced file 


nextfile() continues the lookup function started by firstfile(). Information on matching 


files is placed in the DIRENTRY structure pointed to by dir. 


dir is returned if the function is successful. 0 is returned in all other cases. 


If the shell cover of the CD-ROM drive is opened after the execution of firstfile(), 


nextfile() will fail and report that the file was not found. 


DIRENTRY structure, firstfile() 
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open 
Opens a file 

Structure 

int open ( 

char *devname, 

int flag 

) 
Arguments 

devname Filename 

flag Open mode 
Explanation 





The file indicated by devname is opened and its file descriptor is returned. 


flag can be set to one of the following macros. 


[wee [renee | 
O_RDONLY Read only 
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Return value 





If the open succeeded, the file descriptor is returned. -1 is returned in the event of 


failure. 


See Also 





close() 
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read 
Reads data from a file 

Structure 

int read ( 

int fd, 

char * buf, 

int n 

) 
Arguments 

fd File descriptor 

buf Pointer to read buffer 

n Number of bytes to read 
Explanation 





n bytes are read from the file specified by fd and placed in the buffer pointed to by buf. 


Return value 





The number of bytes read up to normal termination is returned. -1 is returned if an error 


occurred. 


See Also 





open() 
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rename 


Structure 





Arguments 


Explanation 





Return value 





Notes 





Renames a file 


int rename ( 


char * src, 

char * dest 

) 

STC Source filename 
dest New filename 


The filename specified by src is renamed to the name specified by dest. The full path 


from the device name must be specified for both src and dest. 


1 is returned if the rename was successful. 0 is returned in all other cases. 


rename() is valid only for writeable file systems. 
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ResetRCnt 


Structure 





Arguments 


Explanation 





Return value 





See Also 
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Resets a root counter 


long ResetRCnt( 
unsigned long spec 


) 


spec The specified root counter 


The root counter specified by spec is reset. 


1 is returned if the root counter was successfully reset. 0 is returned in the event of 


failure. 


GetRCnt(), StartRCnt() 
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SetVideoMode() 


Structure 





Arguments 


Explanation 





Return value 





Notes 





See Also 





Sets the currently active video signal mode 


long SetVideoMode ( 


long mode 

) 

mode Video signal mode 
MODE NTSC: NTSC video signal mode 
MODE PAL: PAL video signal mode 


The currently active video signal mode is set to mode for use by the library functions. 


The previously active video signal mode is returned. 


SetVideoMode() should be called before any library functions. 


GetVideoMode() 
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StartRCnt 
Starts a root counter 

Structure 

long StartRCnt ( 

unsigned long spec 

) 
Arguments 

spec The specified root counter 


Explanation 


The root counter specified by spec is activated and enabled for interrupts. 


Return value 





1 is returned if the root counter was successfully activated. 0 is returned in the event of 


failure. 


See Also 





GetRCnt(), ResetRCnt() 
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TestCard 
Test a memory card 
Structure 
long TestCard ( 
long chan 
) 
Arguments 
chan Slot number of memory card 
0: Slot 1 
1: Slot 2 
Explanation 





The memory card in the slot specified by chan is tested and the result of the test is 


returned. 


Card initialization is performed from the memory card control screen of the PlayStation. 


One to four vertical synchronization interruptions must be performed at the end of the 


operation (17 msec to 68 msec). 


Return value 





The test result is indicated in the return value as shown below. 


0: 
1: 


Card missing 

Card present 

New card detected 

Communication or card error detected 


Uninitialized card detected 
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write 
Writes data to a file 

Structure 

int write ( 

int fd, 

char * buf, 

int n 

) 
Arguments 

td File descriptor 

buf Pointer to data write buffer 

n Number of bytes to write 
Explanation 





The first n bytes from the buffer pointed to by buf are written to the file specified by fd. 


Return value 





The number of bytes written up to normal termination is returned. -1 is returned if an 


error occurred. 


See Also 





open() 


342 


Other Structures and Functions EEE 





_get_errno 


Structure 





Arguments 


Explanation 





Return value 





Obtains i/o error code 


long _get_errno ( void ) 


None 


The cumulative error code from all file descriptors is obtained and its value is returned. 


The error code is defined in sys/errno.h. 


The error code is returned. 
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ioctl 


Controls i/o devices 


Syntax 





long ioctl (fd, com, arg) 
long fd; 

long com; 

long arg; 


Arguments 





fd File descriptor returned by a preceding call to open() 
com Control operation to be performed (macro defined in sys\ioctl.h) 
arg Control command argument 


Explanation 





ioctl() executes control commands(i.e. set baud, reopen, etc.) on the PlayStation I/O 
devices(ie tty, bu, etc). The Control Command macros are defined in include\sys\ioctl.h. 
Please refer to the I/O Control Management section of the Kernel Management chapter 


for more information. 
Return value 





Returns the value “1” if it succeeds and the value “0” otherwise. 


See also 
open(), read(),write(), close() 
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ApplyMatrix, 49 
ApplyMatrixLV, 50 
ApplyMatrixSV, 52 
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atan, 274 

atan2, 275 
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atoi, 213 
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CdlFILE, 304 
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ClearImage, 54 
close, 313 
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DrawSync, 57 


=E 


EnterCriticalSection, 316 
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getchar, 224 
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GetPadBuf, 324 
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GetTPage, 64 
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GsInitGraph, 86 
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GsMAP, 33 
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GsOT, 35 
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GsSetRefView2, 110 
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GsSortClear, 115 
GsSortFastSprite, 116 
GsSortFixBg16, 118 
GsSortGLine, 120 
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GsSortLine, 121 


GsSortObject4, 122 


GsSortOt, 124 
GsSortSprite, 125 
GsSPRITE, 40 


GsSwapDispBuff, 127 


GsVIEW2, 44 
gteMIMefunc, 129 
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hypot, 286 


= 


InitHeap, 328 
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KanjiFntClose, 131 
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log10, 289 
longjmp, 229 
lseek, 331 


—M— 


malloc, 230 
MATRIX, 45 
memchr, 231 
memcemp, 232 
memcpy, 234 
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memmove, 235 
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PopMatrix, 144 
pow, 291 

printf, 237 
printf2, 293 
PushMatrix, 145 
putc, 238 
putchar, 239 
PutDispEnv, 146 
PutDrawEnv, 147 
puts, 240 
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